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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is fully covered. The description adds that output consists of per-room metrics plus rankings, but says nothing about prerequisites (rooms actually having thermostats/valves), data gaps, or cost of a 30-day window. Useful framing, no deeper behavioral disclosure.

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. The core action and the default window are front-loaded, followed by the concrete metric list and the return shape.

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 full schema coverage, a present output schema, and read-only annotations, the description carries the remaining burden well by naming the derived metrics and rankings. It could still mention that rooms lacking thermostat data are omitted or reported as insufficient, which matters for interpreting a comparison across all rooms.

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 contributes something the schema does not state: that the default period is the last 7 days. It still adds nothing about the from/to vs period interaction or home_id resolution beyond the 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 ('Compare all rooms over a period') and then enumerates the exact comparisons produced: warmest/coolest, most variable, most time below target, largest drop, fastest cool-down. This cross-room ranking scope cleanly separates it from the single-room status tools and the home-level heating summary siblings.

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

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

The description makes clear the tool is for period-based cross-room comparison and discloses the default window (last 7 days), which tells an agent when it is safe to call with no time arguments. It does not explicitly say when to prefer a sibling (e.g. netatmo_get_temperature_history for one room), so there is no exclusion guidance, but usage context is unambiguous.

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 the tool is read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: the detection is rule-based, operates on 30-minute readings, has a bounded default and maximum range, and returns findings with severity, confidence, evidence, and explanation. It also clarifies that findings are observations, not diagnoses.

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 leads with the detection method and data scope, then enumerates anomaly types, then describes findings. Every sentence contributes useful information without 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 read-only annotations, full schema coverage, and an output schema present, the description supplies everything the agent needs: the detection scope, time bounds, anomaly categories, and the structure and interpretive limits of findings. No critical behavioral or output information 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 the input schema fully documents the seven parameters. The description adds only indirect parameter context through the default window and maximum 14-day range, which is consistent with the baseline of 3 when the schema carries the main documentation burden.

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 operation, rule-based detection of unusual readings, and scopes it to 30-minute room data with a bounded time window. This clearly distinguishes it from sibling tools that retrieve summaries, statuses, or histories rather than detecting anomalies.

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 useful context such as the default last 24 hours and maximum 14-day window, but it does not explicitly state when to choose this tool over siblings like netatmo_get_temperature_history or netatmo_get_heating_summary. Usage is implied by the anomaly-detection purpose rather than spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for adding semantics annotations cannot express: the metric is heat-demand duration, not energy, and a thermostat is required. It stops short of describing bucket edge cases or gaps in data.

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 number means and the prerequisite, then the semantic caveat, then the default. 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 an output schema present, return values need no explanation, and annotations cover safety; the description supplies prerequisites, unit semantics, and default range. What is missing is explicit positioning against the many sibling history 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?

Schema coverage is 100%, so the baseline is 3, but the description adds one genuine fact not present in the schema: the default range is yesterday. It does not explain mode/scale interplay (that lives in the schema), which is acceptable given full coverage.

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 (boiler heat-request history) plus the unit of measure (minutes and share of time, per bucket), and explicitly excludes a likely misreading by saying it is heat-demand time, not gas or energy consumption. It does not name a sibling such as netatmo_get_temperature_history to sharpen the boundary, so it falls just short of 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?

'Requires a Netatmo thermostat' is a useful prerequisite and 'Default: yesterday' sets a default context. However, there is no explicit when-to-use / when-not guidance relative to siblings like netatmo_get_heating_summary or netatmo_get_setpoint_history, leaving the choice 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds the diagnostic content returned (battery, signal, firmware, error codes), which is useful, but says nothing about permissions, freshness of diagnostics or rate limits.

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

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

A single front-loaded sentence that names the diagnostic fields first and the scope last. No redundant clauses or 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?

An output schema exists, so return structure need not be explained, and the annotations cover the safety profile. The description is sufficient for a 2-param read tool, with only minor missing context about prerequisites or data freshness.

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

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

Schema coverage is 100%, so both home_id and device_id are already documented, including the 'omit for all devices' semantics. The description's 'or of one device' merely echoes that; no additional format or dependency details are added.

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 resource (device diagnostics) and enumerates the exact data returned: battery, radio/Wi-Fi signal, reachability, firmware and error codes. Scope is clear (all devices of a home or one device), which differentiates it from sibling status tools like netatmo_get_home_status or netatmo_get_heating_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?

The scope 'all devices of a home, or of one device' implies usage, but there is no explicit when-to-use guidance, no mention of prerequisites (e.g. call netatmo_list_devices first), and no named alternatives. Usage is inferable rather than stated.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and openWorld behavior. The description adds semantic context that prevents conflating heating demand with boiler power/energy use, which is useful beyond the annotations. It does not need to explain return values because an output schema exists.

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

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

Two tightly written sentences front-load the tool's output content and immediately follow with a clarifying exclusion. Every sentence carries useful information with no waste.

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 rich annotations, a full output schema, and complete parameter documentation, the description is nearly complete for calling the tool. The main omission is any pointer to the closely related netatmo_get_heating_summary sibling, which would help an agent choose correctly among many status 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?

Schema description coverage is 100%, and the single home_id parameter is fully documented in the schema, including its optionality and reference to netatmo_list_homes. The description adds no parameter-specific meaning beyond that, so the baseline 3 is appropriate.

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

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

The description states concrete content: boiler heating request status, per-room heating demand percentages, and anticipation. It also rules out a likely misinterpretation ('Demand is not boiler power or energy use'). However, it does not differentiate this tool from the sibling netatmo_get_heating_summary, leaving overlap ambiguous.

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

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

Usage is only implied. The caveat that demand is not boiler power or energy use hints that other tools (e.g., history tools) should be used for energy data, but no alternative is named and there is no explicit when-to-use/when-not-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 cover safety (readOnly, idempotent, non-destructive), so the bar is lower. The description adds two useful behavioral facts beyond them: the calculations are deterministic/reproducible, and energy or gas figures are not included. Pagination, cost and rate-limit behavior remain unmentioned, but they are less central here.

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: the output content is front-loaded, the default and the exclusion follow. No repetition or filler. Slight density in the first sentence's list, but it earns its place by defining the tool's output.

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 the description need not explain return shape, yet it still enumerates the headline metrics, and it covers defaulting and the data it refuses to produce. The one missing piece for a read-only analytics tool surrounded by history/status siblings is explicit disambiguation from them.

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, and the description earns one step above it by disclosing the default window ("yesterday") that the schema does not state for the period/from/to trio. It adds no further detail on room_id vs room_name resolution, which the schema handles.

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

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

The description names the specific resource (per-room temperature statistics, mean setpoint, time below/within/above target, cool-down rate, boiler heat-demand time) so the agent knows exactly what is computed. It also states what is deliberately excluded ("no energy or gas figures"). It stops short of naming which sibling (e.g. netatmo_get_temperature_history or netatmo_compare_rooms) to prefer over it.

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

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

"Default: yesterday" supplies the no-argument behavior, which is genuine usage guidance, and the exclusion of energy/gas figures implicitly steers an agent away from this tool for consumption data. However, there is no explicit statement of when to choose this over the many heating-oriented siblings such as netatmo_get_heating_status or netatmo_compare_rooms.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description contributes the genuinely useful caveat that results are topology only (not live values), which prevents misuse; it says nothing about auth requirements or error behavior, but with annotations present that gap is minor.

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

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

A single sentence with the scope front-loaded and the disambiguating caveat in parentheses. Nothing is padded or repeated from structured fields.

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 present and annotations covering safety, the description only needs to frame scope, and it does so well. The one gap is that listing 'schedules' alongside a netatmo_get_schedules sibling leaves it unclear whether schedule definitions or merely schedule references are returned.

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

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

Schema coverage is 100% and the schema text already explains that home_id comes from netatmo_list_homes and is optional for single-home accounts. The description says 'one home' but adds no format, fallback, or resolution detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Details of one home') and enumerates the payload scope: heating mode, schedules, rooms, devices. It explicitly distinguishes itself from the status family, so an agent can separate it from netatmo_get_home_status or netatmo_list_rooms without opening a 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 parenthetical 'use the status tools for live values' gives an explicit when-not-to-use rule and points at an alternative tool family. It stops short of naming the exact sibling (netatmo_get_home_status) and doesn't clarify the overlap with netatmo_get_schedules, which it also claims to cover.

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 readOnly, idempotent, non-destructive, and the description correctly does not contradict them. It adds useful payload visibility (boiler state, unreachable devices, low batteries, open windows), but says nothing about freshness/latency, single-home defaulting, or error behavior for unreachable devices — which is what an agent most needs here.

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

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

A single tight sentence with no filler, and the most salient content (current temperature/setpoint/mode) comes first. The structure is a noun phrase rather than a verb-led statement, which slightly weakens front-loading of intent.

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?

Output schema exists, so re-listing return fields is redundant rather than harmful, and the parameter is fully documented by the schema. What is missing is the ambiguous-case handling: when to pick this over the heating summary, room status, or room comparison siblings, and whether it covers one home or all homes.

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 one parameter at 100% schema description coverage, the schema already explains home_id and even points at netatmo_list_homes and the single-home default. The description adds nothing about the parameter, so baseline 3 applies.

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

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

The description enumerates what the tool reports (per-room temperature/setpoint/mode/demand, boiler on/off, alerts), which makes the resource scope clear even though it omits an explicit verb. It does not distinguish itself from close siblings such as netatmo_get_room_status, netatmo_get_heating_status, or netatmo_get_heating_summary, so an agent cannot route on the text alone.

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 when-to-use guidance and no mention of alternatives, despite four deployed siblings that return overlapping room/heating data. The only implicit cue is the word 'every room', which hints at whole-home scope but is never stated as a selection 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 establish this as a safe, idempotent, read-only call, so the burden is lower. The description adds value by disclosing the data payload (mode, heating demand, open-window state) and the dual identification paths, but says nothing about data freshness, behavior when a room is not found, or the multi-home fallback.

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

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

Two tightly written sentences with no filler; the returned payload leads and the identification rule follows. Slightly more front-loading of identification (a prerequisite for calling) would be ideal, but nothing is wasted.

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 present and annotations covering the safety profile, the description only needs to scope the call and preview the payload, which it does. Minor gaps remain around freshness of 'current' readings and the single-home default for home_id, but neither blocks 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 coverage is 100%, so the schema already documents home_id, room_id and room_name, including the 'Use room_id or room_name' either/or rule. The description restates that identification choice without adding format, precedence, or ambiguity-resolution detail, so baseline 3 applies.

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

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

The description names the resource precisely — one room — and enumerates the returned values (measured temperature, setpoint, setpoint mode, heating demand, open-window state). The phrase 'of one room' implicitly separates it from home-level siblings like netatmo_get_home_status, but no sibling is 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?

Usage is only implied by scope: 'one room' suggests this is the per-room read rather than the aggregate views offered by netatmo_get_heating_summary or netatmo_compare_rooms. There is no explicit when-to-use or when-not statement, and no guidance on handling multiple rooms or cross-referencing 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the payload includes the active schedule indicator, which is useful selection context but is largely restating return content already covered by the output schema. No mention of payload size, rate limits, or auth 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?

Two tight sentences with no filler, and the core resource is front-loaded. The inline enumeration is dense but each item carries informational value for judging tool fit; only the 'day + time + zone' phrasing is slightly cryptic.

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?

Annotations cover the safety profile, the schema covers the lone optional parameter, and an output schema exists to describe return structure. The description supplies the conceptual shape of the schedule data (zones, setpoints, timetable, active schedule) which is enough for correct selection and 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?

With a single optional home_id at 100% schema description coverage, the schema already explains that the ID comes from netatmo_list_homes and is defaulted for single-home accounts. The description contributes no additional parameter meaning, 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 noun phrase 'Weekly heating schedules of a home' plus the enumerated contents (zones, setpoints, away/frost-guard temperatures, timetable, active schedule) makes the resource concrete and distinguishes it implicitly from siblings like netatmo_get_heating_summary and netatmo_get_heating_status. It lacks a leading verb ('Retrieve...') but an agent can still identify it as a read of schedule configuration rather than live 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?

Usage is only implied — an agent infers this is the tool for static weekly programming as opposed to current heating status, but nothing in the description states when to prefer it over netatmo_get_heating_status or netatmo_get_heating_summary. No prerequisites, exclusions, or alternatives are named.

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 readOnly/idempotent/non-destructive safety, so the bar is lower, and the description still adds value: the returned data includes the periods during which each setpoint applied, and it states the default range. It does not discuss pagination or bounded-detail behavior, hence not a 5.

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 with no waste, and the content type plus default time window are front-loaded. 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 an output schema present, return values needn't be explained, and the description gives the resource scope plus default window for a 9-parameter tool. It falls slightly short by not clarifying that a room must be selected via room_id or room_name despite zero required params in the schema.

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

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

Schema description coverage is 100%, so all nine parameters (including from/to, mode, scale, period, max_points) are already documented in the schema. The description adds only the default range, not the syntax or format of any parameter, so baseline 3 applies.

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

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

States a specific verb+resource: setpoint (target temperature) history of a room, and adds that it includes the periods each setpoint applied. It implicitly distinguishes from netatmo_get_temperature_history (actual vs. target temperature) but never names a sibling explicitly, keeping it just shy 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 default of 'last 24 h' is conveyed, but there is no statement of when to choose this over alternatives like netatmo_get_temperature_history or netatmo_get_heating_status, nor any prerequisites or exclusions. Usage is only implied through the resource wording.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds genuine behavioral context that the annotations cannot: the aggregation default and the guarantee that 'missing data is reported, never filled in', which tells the agent to expect gaps rather than interpolated values. It does not mention response size limits or paging beyond what max_points already implies.

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

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

Three short clauses, each earning its place: what is returned, what the defaults are, and the data-quality guarantee. The most decision-relevant facts (content and default window) are front-loaded with zero 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 an output schema present, nine richly documented parameters and complete annotations, the description only needs to add the defaults and any surprising behavior, which it does. The one gap is that it never states that a room identifier (room_id or room_name) is effectively required, even though the schema lists zero required parameters — an agent could call it unscoped and be confused by 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 description coverage is 100%, so all nine parameters — including the mode, scale and period enums — are already fully documented in the schema. The description only restates the default ('last 24 h, aggregated') and adds no extra meaning about how period and from/to combine or which of room_id/room_name to prefer. Baseline 3 applies when the schema does the heavy lifting.

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 resource (measured room temperature history) plus the exact payload (min/max/mean/variability statistics and coverage/gaps), which separates it from status-style siblings like netatmo_get_room_status. It does not explicitly name the siblings it should be preferred over (compare_rooms, detect_anomalies), so the differentiation is implied by the word 'history' rather than stated.

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 'Default: last 24 h, aggregated' clause tells the agent what happens when it supplies nothing, and the schema explains how period/from-to and mode interact. However the description gives no explicit when-to-use guidance — nothing says to use this for trends/coverage vs. netatmo_get_room_status for the current reading, or vs. netatmo_get_setpoint_history for targets.

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, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds value by stating the content of the result set (model, room, gateway) and by carving off status-type data to a sibling. It does not mention auth or rate-limit behavior, but those gaps are minor given the annotation coverage and the existing output schema.

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. The scope statement is front-loaded and the sibling routing follows immediately, which is the correct order for an agent scanning for selection signals.

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-optional-parameter read tool with a rich annotation set and an output schema, the description supplies everything an agent needs: what comes back, the scope of the listing, and where to go for adjacent data.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including the 'optional when the account has a single home' rule. The description's phrase 'of a home' echoes rather than extends that, so the baseline 3 is appropriate.

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

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

Names a specific verb ('List') and enumerates exactly which resources are returned (thermostats, radiator valves, relays/gateways) plus the fields attached to each. This distinguishes it cleanly from netatmo_get_device_status, which the description explicitly routes elsewhere.

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 alternative (netatmo_get_device_status) and the condition that selects it: battery, signal and reachability queries. The scope 'of a home' combined with the schema's note that home_id is optional for single-home accounts leaves little inference required.

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, open-world behavior, so the safety profile is covered. The description adds the filtering behavior (homes without Energy devices are excluded), which is genuine value, but the rest of the sentence largely restates what an output schema would 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?

A single tight sentence with the resource front-loaded and no filler. Slightly dense with multiple clauses (scope, device types, counts, boiler history) but every element informs the caller.

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 zero params, an output schema covering return values, and annotations covering safety, the description only needs to establish scope — which it does. The one remaining gap is routing versus netatmo_get_home, which is not addressed.

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?

Zero parameters, so the baseline of 4 applies; there is nothing parameter-related the description could or should explain.

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

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

Specific verb+resource (list homes) plus a meaningful scope qualifier (only homes with Energy devices) and a preview of the returned fields (room/device counts, boiler history). It does not, however, differentiate from the close sibling netatmo_get_home, so an agent could hesitate between the two.

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

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

Usage is only implied: the filter on Energy devices hints that this is the entry point for heating workflows, but there is no explicit 'use this before X' instruction and no mention of netatmo_get_home or netatmo_list_devices as 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 readOnly, idempotent, non-destructive and open-world behavior, so the safety profile needs no restating. The description adds only that devices are included per room; it discloses nothing about pagination, missing homes, or permission requirements. That is acceptable against rich annotations but not generous.

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

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

One front-loaded sentence with the verb and resource first and the return content after, with zero boilerplate or filler. Nothing 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?

An output schema exists and annotations cover the safety profile, so the description needn't explain returns or side effects. With only one optional parameter fully documented, the definition is callable as-is; only the sibling routing is left implicit.

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 single home_id parameter is already documented with its source (netatmo_list_homes) and its optionality for single-home accounts. The description adds no parameter meaning beyond that, so baseline 3 applies.

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

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

States a specific verb (List) plus the resource (rooms of a home) and enumerates the payload fields (IDs, types, installed devices). This separates it from netatmo_get_room_status and netatmo_compare_rooms at a glance, though it never names those siblings 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?

The 'list' framing implies a discovery/browse step, and the schema note pointing to netatmo_list_homes implies the ordering of calls. However, no explicit when-to-use or when-not-to-use guidance versus netatmo_get_room_status or netatmo_compare_rooms is given anywhere in the description.

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