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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint; the description reinforces these by saying 'Liest' and adds specific payload details plus the return type as a JSON string. It does not cover auth/rate limits, but for a no-input read-only getter the added behavioral context is sufficient.

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

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

The description is compact and front-loaded with the core action, followed by a structured itemized list of returned values. Minor redundancy between the 'Liefert' list and the 'Returns' line prevents a perfect score, but overall it is efficient and well organized.

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 zero parameters, an output schema, and full annotations, the description provides complete context for selecting and invoking the tool. It explicitly lists all relevant status categories—compressors, pumps, and switching valves—making the tool's coverage clear without needing to explain return values thanks to the existing output 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?

The tool has zero parameters, so the baseline is 4. The description correctly omits parameter details, and the empty input schema aligns with the no-input behavior, requiring no additional semantic explanation.

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 uses a specific verb 'Liest den Status' and enumerates exact items (compressors 1–4, pumps M15/M16/M17/M84, valves M61–M99), clearly distinguishing it from sibling tools such as temperature or hot water status tools. The title and description consistently identify the resource domain as compressor/pump 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?

No explicit when-to-use or when-not-to-use guidance is provided, and no alternative sibling tools are named. The description implies usage for compressor/pump status by listing the returned data, but it does not clarify boundaries relative to broader status tools like idm_get_system_status.

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 covered. The description adds value by enumerating the returned quantities (Momentanleistung, Leistungsaufnahme WP, cumulative heat quantities) and specifying units kW/kWh. No contradictions with annotations.

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

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

The description is concise and well-structured: a lead sentence states the action, a bullet-like list details the returned data, and a short note covers the return format. It is front-loaded with the verb and contains no unnecessary 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 parameterless, read-only tool with a declared output schema and helpful annotations, the description covers all relevant energy data categories and units. It is fully self-contained for selection and basic invocation, and the output schema can supply any remaining structural details.

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 the input schema is already complete and there is nothing for the description to clarify. Per the rubric, a zero-parameter tool gets a baseline of 4.

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 begins with the specific verb 'Liest' (reads) and identifies the resource 'Energiezähler und Momentanleistungen der IDM Wärmepumpe'. It clearly distinguishes this tool from sibling status/temperature/solar tools by focusing on energy meters and power values.

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?

No explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives such as idm_get_temperatures or idm_get_compressor_status mentioned. The intended usage is implied by the list of energy-related data returned, but it is not stated directly.

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, covering the safety profile. The description adds context about the returned data fields and operating modes, but does not disclose any additional behavioral traits like authentication needs or rate limits. No contradiction with annotations.

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

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

The description is concise and front-loaded with the primary purpose. It provides essential details in two sentences plus a returns line, with no unnecessary filler. Every sentence adds value.

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

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

Given that there are no parameters and an output schema exists, the description is complete. It clearly states what the tool returns (JSON object with heating circuit data for HK A–G) and the specific data items included, so an agent has sufficient context to invoke and interpret the result.

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

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

The tool has no parameters, so the description does not need to explain any. The schema coverage is trivially 100%, and the baseline for zero parameters is 4, which 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 explicitly states it reads the status of all heating circuits (A–G) of the IDM heat pump, using a specific verb 'liest' (reads) and a clear resource. It distinguishes itself from siblings by focusing specifically on heating circuits and listing the exact data fields and operating modes.

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?

No explicit guidance on when to use this tool versus alternatives, such as idm_get_temperatures or idm_get_system_status. The use case is implied by the description's focus on heating circuit status, but there are no exclusions or alternative references.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Liest' (reads) is consistent with this. However, the description adds no behavioral traits beyond what annotations provide—it only lists output fields and the return type, without discussing auth, rate limits, or side effects.

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

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

The description is compact and front-loaded: it states the purpose first, then lists the delivered data points, and ends with the return type. There is no fluff or irrelevant detail.

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

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

Given that the tool has no parameters, has annotations covering safety, and an output schema (though not shown), the description is complete for the intended use. It lists all the specific B-numbers and states the JSON return format, providing enough context for an agent to select and invoke the tool correctly.

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

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

The tool accepts no parameters, so the schema is empty. The baseline for zero parameters is 4; the description doesn't need to explain parameters, and it doesn't harm clarity.

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 it reads the hot water and drinking water status of the IDM heat pump, and it provides a detailed list of the exact data fields returned. This specific resource (hot water/Trinkwasser) distinguishes it from sibling tools like idm_get_system_status or idm_get_temperatures.

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 no explicit guidance on when to prefer this tool over its siblings. It does not mention alternatives, exclusions, or prerequisites, so an agent is left to infer usage from the tool's name and description.

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 destructiveHint, so the safety profile is covered. The description goes further by enumerating the exact data fields returned (B73, B75, etc.), adding meaningful context about the tool's scope.

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 short and front-loaded, but there is minor redundancy between the German list of returned values and the English 'Returns' line that says 'JSON-Objekt mit Solardaten'. This slightly reduces conciseness but does not harm clarity.

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

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

Given the tool's zero parameters, strong read-only annotations, and existing output schema, the description adequately covers the data scope. It lists all major measurements and states the return format, making it complete for its simplicity.

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 detail to add. The schema is fully covered (100%) and the description correctly omits parameter information, matching the baseline for parameterless tools.

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 uses a specific verb ('Liest') and identifies the exact resource (Solarstatus der IDM Wärmepumpe), then lists the precise measurements returned. This clearly distinguishes it from sibling getter tools like idm_get_temperatures.

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 solar-specific data list implies when the tool is useful, but there is no explicit guidance on when to use it versus alternatives, nor any exclusions or comparisons with sibling 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds value by listing the exact return fields, revealing the tool's behavioral output without relying on the output schema. No contradictions with annotations.

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

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

The description is compact and front-loaded, with the first sentence stating the verb and resource, followed by a bullet-like list of returned fields and a clear return type statement. Every sentence contributes information without redundancies.

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 zero-parameter, read-only getter with comprehensive annotations and an output schema, the description fully covers the tool's purpose, return content, and usage context. There are no gaps in required information.

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, and the input schema confirms this with 100% coverage. With no parameters to describe, the baseline of 4 applies; the description does not need to add parameter-specific details.

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 explicitly states the tool reads the general system status of the IDM heat pump and enumerates the specific fields returned (e.g., operating mode, fault number, smart-grid status, PV surplus). This distinguishes it clearly from sibling getters like idm_get_temperatures or idm_get_compressor_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 description provides a clear context by listing exactly what status information is returned, making it obvious when a high-level system overview is needed. However, it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of full 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds value by listing which specific temperature sensors are included and the unit (°C), going beyond the annotations. It does not mention rate limits or error behavior, but given the strong annotation coverage, this is adequate.

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 succinct and front-loaded with the main purpose. The sensor list is neatly formatted, and the return type is stated. Although it includes bilingual content, each sentence serves a purpose and nothing is extraneous. It is appropriately sized for a simple getter.

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?

This is a zero-parameter, read-only tool with a clear output schema and strong annotations. The description fully covers what data is returned and in what format. No additional context is needed for a competent agent to invoke this tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly notes that it returns a JSON object with all temperatures, which indirectly confirms no input is needed. There is no parameter documentation needed, and the description provides no conflicting information.

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

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

The description clearly states the tool reads all temperature sensors of the IDM heat pump, and enumerates the specific sensors (B33, B34, etc.). This is a specific verb+resource, and it is distinct from sibling getters like hot water status or compressor 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 description gives clear context by identifying the exact purpose (temperature readings) and the scope (all sensors). It does not explicitly name alternative tools or say when not to use it, but the context from the name and sibling list is sufficient to infer appropriate usage. This is a step above no guidance but lacks explicit exclusions.

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. The description adds valuable context by specifying the exact values read (Außentemperatur, Betriebsart, Summenstörung) and the return format (JSON object with connection status), enriching the behavioral profile without contradicting the annotations.

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

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

Three short sentences deliver purpose, operational details, and return format with no redundant content. The mixed German/English is minor and does not detracts from clarity; 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 zero parameters, strong annotations (readOnly, idempotent, non-destructive), and an output schema already present, the description covers all necessary aspects: what it does, what it reads, and what it returns. It fully equips an agent to decide when to use it and what to expect.

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, and the input schema is empty. The description therefore does not need to explain parameters; the baseline for a parameterless tool is 4. It correctly avoids inventing parameter information.

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 'Prüft die Modbus-TCP-Verbindung zur IDM Wärmepumpe', which clearly states the action (checks connection) and the target resource. It explicitly frames the reads of specific values as a connection test, distinguishing it from sibling getter/setter tools that focus on specific data domains.

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 phrase 'als Verbindungstest' explicitly indicates the intended use is to verify connectivity to the heat pump. While it does not name alternatives such as idm_get_system_status or suggest when not to use it, the sibling list makes its unique diagnostic role apparent, providing clear context without exclusions.

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

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

The description reveals critical behavioral traits beyond the annotations: the registers must be written cyclically and the demand is not retained after a restart. This is important operational context not captured by the annotations (readOnlyHint=false, destructiveHint=false). It also states the return type (JSON confirmation). The description does not contradict any annotations.

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

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

The description is compact and well-structured: a one-sentence purpose, a prominent warning about cyclic writes, a usage list mapping flags to registers, and a clear Args/Returns section. Every sentence earns its place without redundancy or excessive length.

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

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

Given the tool's moderate complexity (three configurable flags, cyclic-write requirement, non-persistent behavior), the description covers all essential aspects: what it does, usage warnings, parameter meanings, and return value. The input schema and output schema presence fill any remaining gaps, making this description complete for an AI agent.

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

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

The input schema already includes per-parameter descriptions with register numbers and the 'ZYKLISCH schreiben!' warning. The description adds value by clarifying the boolean semantics: 'True=Ein, False=Aus' and grouping them under the 'params' object. This compensates for the 0% schema description coverage in the top-level description and reinforces the register mappings.

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

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

The description opens with a specific verb+resource: 'Setzt externe Heiz-, Kühl- und/oder Warmwasseranforderungen' (sets external heating, cooling, and/or hot water demands). It maps each demand to a specific register (1710, 1711, 1712), which distinguishes it from sibling getter tools and other setters like idm_set_system_mode. This makes the tool's purpose immediately 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?

Provides strong usage guidance by stating that the registers MUST be written cyclically (e.g., every 30 seconds) to ensure the demand is reapplied after a heat pump restart. It also explains the meaning of each parameter flag. However, it does not explicitly state when-not to use this tool or mention alternatives, so it falls slightly 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?

The EEPROM write-cycle warning adds significant behavioral context beyond what annotations provide (readOnlyHint=false, idempotentHint=true). It also discloses the return format ('JSON-Bestätigung') and the requirement for at least one parameter. However, the 'mit * markiert' reference is confusing because no asterisks are present on the listed parameters.

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 well-structured with a warning, parameter list, and args/returns section. The content is necessary and front-loaded, but the language is verbose and the 'mit * markiert' phrasing is distracting and unclear.

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

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

Given the tool's moderate complexity (nested parameters, EEPROM risk), the description adequately covers purpose, constraints, return value, and the critical write-cycle warning. It does not mention error handling or prerequisites beyond the parameter requirements, but the schema and annotations fill some 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?

The description lists the three parameter names with register numbers and labels, but does not explain units or ranges. The schema descriptions partially cover this, but with schema_description_coverage at 0%, the description must compensate. It adds the 'at least one' rule, but more detail on the meaning of 'Einschalttemperatur' vs 'Ausschalttemperatur' would be useful.

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 that the tool sets hot water setpoint temperature, switch-on and/or switch-off temperature ('Setzt Warmwasser-Solltemperatur, Ein- und/oder Ausschalttemperatur'). This is a specific verb+resource combination that distinguishes it from sibling getter tools like idm_get_hot_water_status and other setters.

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

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

The description provides critical usage constraints: 'NICHT permanent oder zyklisch schreiben – nur bei Bedarf ändern' (do not write permanently or cyclically, only change when needed) and 'Mindestens einen der drei Parameter angeben' (at least one parameter must be specified). It clearly implies when to use this tool (for changing setpoints), but it does not explicitly name alternatives or exclusions.

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?

Despite annotations indicating readOnlyHint=false and other hints, the description reveals non-obvious behavioral traits: the temporary override behavior ('überschreibt die E3DC-Vorgabe TEMPORÄR bis zum nächsten E3DC-Zyklus') and the requirement for cyclic writing. It also explains the resulting heat pump behavior. This goes well beyond the structured annotation data, which does not disclose these transient effects.

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

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

The description includes a warning and explanatory details, which are relevant and each sentence contributes value. It is slightly long but well-structured with a clear warning block and separated sections for args/returns. The front-loaded main sentence immediately states the purpose, and the rest supports it without excessive verbosity.

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 that this is a single-parameter setter with a documented output (JSON confirmation), the description covers the core behavior, critical integration context (E3DC), and required usage pattern. It lacks some edge-case details like error handling or authentication, but for its complexity, it is reasonably 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 input schema already provides a clear description for pv_ueberschuss_kw (units, register, constraints). The tool description additionally explains the parameter's role in triggering heat production and emphasizes the cyclic requirement, adding operational meaning beyond the schema. Although the schema description is already strong, the description enriches the semantic context.

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

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

The description clearly states the tool's function: 'Schreibt den aktuellen PV-Überschuss an die IDM Wärmepumpe (Register 74).' This identifies the specific verb (schreibt), resource (IDM Wärmepumpe), and target register. It distinguishes itself from sibling getter tools and other setters by focusing on PV surplus communication.

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

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

The description provides critical usage context: it warns that the E3DC system writes this value automatically and that direct writes only temporarily override until the next E3DC cycle. It explicitly states 'Dieser Wert muss ZYKLISCH geschrieben werden – nicht einmalig!' This gives clear when-to-use and when-not-to-use guidance, though it does not explicitly name alternative 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 signal a write operation (readOnlyHint=false) and idempotency. The description adds the register address and the behavioral meaning of each mode (e.g., '0 = EVU-Sperre & kein PV-Ertrag'), providing context beyond the annotations without contradiction.

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 organized with a purpose sentence, a mode breakdown, and a future-use note, followed by Args/Returns. Every section is informative; 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 a single parameter, a detailed parameter explanation, a return type, and relevant usage context, the description is self-sufficient. The output schema further clarifies the response structure, and annotations cover the safety profile.

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 description includes an 'Args' section explaining params.status with the 0/1/2/4 semantics, complementing the schema's property description. This fully covers the parameter, even though the schema already documents it.

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 clear verb+resource statement ('Setzt den Smart Grid Status der IDM Wärmepumpe (Register 1006)') and expands on the meaning of each status value, distinguishing it from sibling setters like idm_set_system_mode or idm_set_pv_surplus.

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 identifies the use case (external control via energy market signals or E3DC/Victron) and even includes a future pricing-based usage hint, but it does not explicitly compare with alternative setters or state when not to use.

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

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

The description goes well beyond the annotations by disclosing the EEPROM write-cycle limitation, the explicit warning against permanent/cyclic writes, and the register address. These are critical behavioral traits not visible from the annotations (readOnlyHint=false, idempotentHint=true), making the tool's side effects and constraints transparent.

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 well-structured: a clear action sentence, a warning block, a value list, and a parameter/return summary. Every sentence earns its place, and the use of line breaks improves readability without unnecessary verbiage.

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 single-parameter setter with an output schema, the description is complete. It covers the purpose, the valid values, the critical write-cycle caution, and the return format. No important context is missing, and it complements the annotations and schema rather than repeating 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?

Despite the schema's modus description, the context signal indicates 0% schema description coverage. The description fully compensates by listing each valid value (0,1,2,4,5) with its meaning, which is exactly the semantic mapping needed for safe and correct invocation. This adds significant value beyond the raw integer constraints.

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

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

The description clearly states the action ('Setzt die Betriebsart') and the specific resource ('IDM-Gesamtsystems'), with the register (1005) and EEPROM note. It is distinct from sibling getters and other setter tools like set_hot_water_setpoints or set_smart_grid.

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 implies when to use the tool (to set system operating mode) and provides a caution against frequent writes, but it does not explicitly contrast with alternative tools or state 'use this instead of X'. The warning is useful usage guidance, but the lack of explicit alternative differentiation keeps it at a minimum-viable level.

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