Get room temperature history

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.