Solvion Heating Energy Engineering

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 no behavioral context beyond the annotations—it doesn't state what happens when capacity is insufficient, what units are used, or what the return format is. With annotations present, the description should add context like output semantics or assumptions, but it does not.

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

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

The description is a single, efficient sentence with no filler. It is appropriately front-loaded, stating the action and objects immediately. There is zero waste; every word contributes to the meaning.

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

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

The tool is simple, but without an output schema, the description must explain what the tool returns or how the comparison is reported. It does not. An agent would be uncertain whether the tool returns a boolean, a numeric margin, or a textual assessment. This is a significant gap for a tool that only has a 2-parameter input and no output schema, making the description incomplete for confident invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It maps 'available boiler capacity' to boiler_power_kw and 'required heating load' to required_power_kw, which adds some meaning. However, it doesn't explain units (though kW is in the names), the expected range, or how the comparison is performed (e.g., threshold or margin). The minimal mapping is insufficient given zero schema 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?

The description states a specific action ('Compare') and a clear resource ('available boiler capacity with required heating load'). It distinguishes from sibling tools like required_heating_power (which computes a value) and heat_loss_total (which calculates losses), making the purpose fairly clear. However, it doesn't specify what 'compare' yields (e.g., a boolean, margin, or recommendation), which slightly reduces clarity.

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 guidance on when to use this tool versus alternatives. It doesn't mention that it should be used when both boiler capacity and required load are already known, nor does it reference any sibling tool. An agent must infer usage from the name and context, which is a notable gap.

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, so the read-only nature is covered. The description adds no additional behavioral context such as output format, performance characteristics, or constraints beyond the vague 'machine-readable assumptions'. It does not contradict the annotations, but it also does not enrich them meaningfully.

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

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

The description is a single, concise sentence with no fluff. It is front-loaded with the core action and resource. However, its brevity sacrifices essential detail, so while it is structurally efficient, it is not fully informative.

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 complexity (nested object parameters, no schema descriptions, no output schema) and the absence of any usage guidance, the description is far from complete. An agent would not know how to format options, what the comparison entails, or what to expect as a result. The description fails to compensate for the lack of structured detail.

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 description does not explain the structure or expected content of option_a and option_b. It only refers to them as 'two preliminary heating options', which is insufficient for an agent to construct valid inputs. The schema shows they are objects with additionalProperties, but no required fields or examples are given.

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 ('compare') and resource ('two preliminary heating options'), and adds 'using machine-readable assumptions' which hints at the input format. It is distinguishable from sibling tools that perform individual calculations (e.g., heat_loss_total, heating_energy_cost). However, it does not specify what the comparison produces or what 'preliminary' implies.

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 guidance is provided on when to use this tool versus its siblings. There is no mention of prerequisites, alternatives, or conditions that would lead an agent to choose this tool over other heating-related tools. The description is silent on usage context.

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 read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds the notion that the result is an estimate, but it does not disclose output format, calculation assumptions, or limitations beyond that.

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

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

The description is a single compact sentence with no filler. It front-loads the operation and resource, then states the input sources, making it easy for an agent to parse quickly.

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, read-only three-parameter calculation, the description is sufficient: an agent can infer to pass power_kw, hours, and price_per_kwh and expect an energy and cost result. There is no output schema, but the description names the outputs at a high level, which is adequate for this tool's 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?

Schema description coverage is 0%, so the description must compensate. It maps 'demand' to power_kw, 'runtime' to hours, and 'tariff' to price_per_kwh, which adds meaning, but it does not explain units, ranges, or the exact relationship between inputs and outputs. The parameter names themselves remain the main semantic source.

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 ('estimate') and a specific resource ('operating energy and cost') with source inputs ('demand, runtime and tariff'). This clearly distinguishes it from sibling heat-loss, capacity, and equipment-offer tools, even without naming a sibling.

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

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

The phrase 'from demand, runtime and tariff' implies the intended use case: when the agent has power, hours, and price per kWh available and wants an energy/cost estimate. However, there is no explicit guidance about when not to use it or how it compares to siblings like compare_heating_options or solve_heating_task.

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 the aggregation scope but does not explain whether 'combine' means a simple sum, how missing/empty components are handled, or anything about output behavior. This is acceptable for a read-only calculation but not rich.

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 compact sentence with no filler. The verb is front-loaded, and the sentence efficiently conveys the tool's purpose and component inputs.

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

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

For a tool with three parameters and no output schema, the description provides the core inputs and purpose but leaves the return format, units, and exact calculation semantics implicit. It is adequate for a straightforward calculation tool but not fully 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It maps ventilation to ventilation_kw and material loads to material_kw, and implies components_kw holds transmission components. However, it does not clarify that ventilation_kw is optional per the schema, and the exact role of components_kw remains somewhat inferred, so compensation is partial.

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, 'Combine', and clearly identifies the resource: transmission, ventilation, and optional process/material loads. This distinguishes it from sibling tools like transmission_heat_loss and ventilation_heat_loss, which handle only individual components.

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 guidance is given about when to select this tool versus alternatives. It does not mention siblings such as specific_heat_loss or required_heating_power, nor any exclusion conditions, leaving the agent to infer the appropriate use case.

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 the tool as read-only, idempotent, and non-destructive, so no safety disclosure is needed from the description. The description adds the approximate nature of the calculation via 'estimate' but does not disclose assumptions, limitations, or output behavior beyond that.

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

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

The description is a single, focused sentence with no wasted words. The core action and required inputs are front-loaded, making it easy for an agent to parse quickly.

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 read-only calculation, the description covers the basic purpose and inputs, but there is no output schema and the description does not specify the output unit or governing relationship. The lack of assumptions or return format leaves some ambiguity for agent use.

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 description only restates the parameter roles ('thermal power', 'temperature difference') without adding meaningful detail. The parameter names already carry that meaning, and no units, constraints, formula, or default values are clarified.

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 specific action: estimate required coolant mass flow from thermal power and temperature difference. This directly distinguishes the tool from siblings like hydronic_pipe_velocity (which concerns velocity) and required_heating_power (which concerns power).

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 the tool should be used when you have thermal power and temperature difference and need coolant mass flow, but it does not explicitly state when to choose it over alternatives. No exclusions or sibling comparisons are provided, so usage context 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 establish read-only, idempotent, and non-destructive behavior. The description adds the round-pipe scope and the word 'estimate', signaling an approximate calculation, but it does not disclose assumptions, return format, or edge cases.

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 with no filler; every word contributes to stating the tool's calculation purpose.

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 parameter descriptions, more context is needed: the result units, the formula or assumptions, and input constraints. The parameter names carry some unit information, but the description itself is too thin for confident 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% and the description mentions neither parameter. An agent gets no explanation of how flow_m3_h and inner_diameter_mm relate, what units or conversions are needed, or what physical assumptions apply beyond the parameter names.

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 clear calculation goal: estimating coolant velocity in a round pipe. It identifies the operation and resource, but it does not differentiate itself from hydronic_mass_flow or other hydronics 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?

No guidance is given on when to use this tool versus alternatives, no exclusions are stated, and no design context is provided. The description only restates the calculation, so the agent must infer usage from the tool name.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context—no mention of pagination, authentication, rate limits, or output format. It simply restates the core action without enriching what annotations already declare.

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

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

The description is a single sentence, front-loaded with the verb 'List' and the resource. Every word earns its place, with no fluff or redundancy. It is appropriately minimal for a parameterless listing operation.

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?

While the tool is simple with no parameters and safety is covered by annotations, the description does not specify what the returned list contains (e.g., fields like model, price, availability) or any pagination/filtering behavior. Since there is no output schema, this information could help the agent understand the expected response, but the description remains functional for a basic listing.

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?

There are zero parameters, and schema coverage is 100% (empty object). Baseline for 0 params is 4, and the description doesn't need to explain any parameters. It correctly avoids adding irrelevant parameter 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 clearly states the verb 'List' and the resource 'available quote-only Solvion machine offers,' making the purpose unambiguous. It also distinguishes from sibling request_machine_quote by indicating this is a listing operation rather than a request action.

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. It doesn't mention conditions for using this over request_machine_quote or other siblings, nor any exclusions. The purpose implies listing, but the agent is left to infer when this is the appropriate choice.

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 that no payment or settlement is executed and that the quote is machine-readable, which is somewhat useful, but it does not disclose additional behaviors such as authentication needs, rate limits, or output format.

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

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

The description is a single sentence with no redundancy. It front-loads the action and the key constraint, and every word 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, no parameter explanation, and no usage guidance, the description is too thin for an agent to invoke the tool correctly. The annotations cover safety, but operational details are 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 0%, and the description does not explain the required capability_id or the free-form inputs object. An agent has no way to know what capability_id refers to or what shape inputs should take.

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

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

The description states a specific action ('Request a machine-readable quote') and explicitly excludes payment/settlement, making the purpose clear. However, it does not differentiate from siblings like list_machine_offers or compare_heating_options, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. The phrase 'without executing payment or settlement' implies a pre-payment quoting context, but no explicit when-to-use or when-not-to-use conditions are provided.

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 adds minimal behavioral context by mentioning an optional reserve, implying the reserve parameter affects the estimate. However, it does not describe output format, assumptions, or any limitations, so it only marginally exceeds the annotation baseline.

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

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

The description is a single, efficient sentence with no fluff. It is front-loaded with the verb and resource. While terse, it is appropriately sized for the tool's simplicity, similar to the update_drive example that scored 4.

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 a single-line description, the tool is underspecified. The agent is not told what the output represents (e.g., required power in kW), how the reserve is applied, or any assumptions about the calculation. For a 2-parameter tool, this is minimally viable but leaves key context 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 0%, and the description does not explain the parameters at all. It mentions 'reserve' generically but does not map it to reserve_percent or explain that heat_loss_kw is the primary input. The description adds no value beyond the bare parameter names in the schema, failing to compensate for the lack of schema documentation.

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 specific action (estimate) on a specific resource (required heating power) with a modifier (optional reserve). It is distinct from sibling tools that focus on heat loss or boiler capacity, though it does not explicitly name a sibling to differentiate from. The purpose is clear enough for an agent to understand what it does.

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 use this tool versus alternatives such as boiler_capacity_check or heat_loss_total. The description does not mention prerequisites, exclusions, or typical scenarios, leaving the agent to infer usage from the name and parameters.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so an agent knows it's a safe, read-only operation. The description adds the 'natural-language' interpretation but doesn't disclose return format or limitations. This is adequate but not rich given the annotation coverage.

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

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

The description is a single focused sentence, with no filler or redundancy. It front-loads the action and resource, and every word 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?

For a tool with one simple parameter and no output schema, the description is adequate for making the call but doesn't explain what the response will contain (a list of capabilities? identifiers? descriptions?). Given the sibling list, an agent could infer it returns relevant capability names, but the description itself leaves that 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 must compensate. It does clarify that 'query' is a natural-language engineering task, which adds meaning beyond the bare 'string' type. But it doesn't give examples, formats, or expected phrasing, so it only partially compensates.

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 ('Find') and a resource ('Solvion machine capabilities'), and adds a qualifier ('relevant to a natural-language engineering task') that distinguishes it from the calculation-oriented siblings. It doesn't explicitly contrast with sibling tools, but the purpose is 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 phrase 'relevant to a natural-language engineering task' implies when to use it (when you have a natural-language task), but it gives no explicit exclusions or alternatives. It doesn't tell the agent when to prefer a specific calculator sibling instead, so 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 idempotentHint=true, covering the safety profile. The description adds only 'preliminary' and 'using the Solvion machine orchestrator,' which do not clarify what happens during execution, what the output looks like, or any side effects beyond the annotations. It does not contradict annotations but adds minimal value.

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

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

The description is a single short sentence, which is concise, but it lacks any structure or useful content. It is under-specified to the point of being unhelpful; the sentence does not earn its place because it provides almost no actionable information. It is more a placeholder than a functional description.

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 generic nature, the presence of 13 specific sibling tools, and the absence of an output schema, the description is severely incomplete. It does not explain the scope of queries it can handle, how it relates to the specific tools, or what the orchestrator does differently. An agent cannot confidently invoke this tool without further 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?

Schema description coverage is 0% and the description makes no mention of the 'query' or 'inputs' parameters. It fails to explain what constitutes a valid query, how to structure inputs, or any constraints. With a nested object parameter and no schema guidance, this is a critical gap.

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

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

The description states a verb ('Run') and a resource ('heating or energy engineering task') but the resource is extremely vague—'preliminary' and 'using the Solvion machine orchestrator' add little specificity. It does not differentiate from the many specific sibling tools (e.g., boiler_capacity_check, heat_loss_total), so an agent cannot tell when this generic solver is appropriate over a dedicated tool.

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

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

There is no guidance on when to use this tool versus the alternatives. It does not mention that specific tools exist for specific tasks, nor does it state any conditions or examples for when the generic orchestrator is the right choice. An agent receives zero direction.

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 useful behavioral context by stating this is a conversion/calculation to W per square metre, which is consistent with 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?

A single sentence with no filler, front-loaded with the verb and resource. Every word contributes to meaning.

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 calculation with readOnly/idempotent annotations, the description conveys the operation and output unit. It does not spell out the exact formula (kW × 1000 / m²), but the parameter names and 'per square metre' make the calculation inferable.

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

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

Schema description coverage is 0%, so the description must compensate, but it only refers to 'total heat loss' and 'per square metre' without explicitly defining heat_loss_kw or area_m2 or the formula relating them. The parameter names carry most of the meaning; the description adds little beyond the output unit.

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 ('Convert') and a precise resource ('total heat loss') with an explicit target unit (W per square metre). This clearly differentiates it from sibling heat_loss_total, which computes the total rather than the area-normalized value.

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 the tool is for normalizing total heat loss by area, but it never states when to choose this over heat_loss_total or other heating-calculation siblings. No explicit when/when-not or alternative routing is provided.

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 only the word 'estimate', which hints at an approximate calculation, but says nothing about computational assumptions, return units, or whether results are in watts or kilowatts. Given the annotation coverage, the description adds minimal behavioral context.

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

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

The description is a single, grammatically complete sentence with no filler or redundant information. It is appropriately front-loaded and every word contributes to the core purpose.

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

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

For a tool with three unannotated parameters and no output schema, a one-sentence description is materially incomplete. It does not explain the expected output, the mathematical model, or how this tool fits with the ten sibling tools, making it hard for an agent to call it correctly in isolation.

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 schema description coverage at 0%, the description must compensate for the bare parameter schema, but it does not. While the parameter names (area_m2, u_value_w_m2k, delta_t_k) are somewhat self-explanatory, the description does not confirm the relationship (e.g., Q = U * A * ΔT) or define what each parameter represents in the context of envelope transmission heat loss.

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 ('estimate') and a distinct resource ('envelope transmission heat loss'), which clearly identifies the calculation being performed. However, it does not differentiate from closely related siblings like heat_loss_total or ventilation_heat_loss, leaving scope ambiguity for an agent.

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 use this tool versus alternatives such as ventilation_heat_loss or heat_loss_total. The description does not state that this tool covers only the conduction component of envelope losses, nor does it exclude scenarios where a different tool would be more appropriate.

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 useful scoping to supplied/exhausted air, but it does not disclose assumptions, calculation formula, or whether the estimate is instantaneous vs. time-averaged.

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

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

The description is a single focused sentence with no filler or redundant restatement of the title. It front-loads the main action and object, earning every word.

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 calculator, the description gives the core intent, but the lack of an output schema means the returned quantity/unit is not specified. It also does not explain how this estimate relates to total, specific, or transmission heat loss, leaving some contextual ambiguity.

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 for parameter meaning, but it does not explain airflow_m3_h or delta_t_k. The names are somewhat self-explanatory (airflow in m3/h, temperature difference in K), yet no units, roles, or relationships are made explicit.

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 ('Estimate') and a specific resource ('heat loss caused by supplied or exhausted air'), which clearly identifies a ventilation-related calculation. It distinguishes from transmission_heat_loss by naming the mechanism, though it never explicitly mentions the sibling tools or contrasts with 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?

No guidance is provided about when to choose this tool over siblings like transmission_heat_loss or heat_loss_total. The description gives no exclusions, prerequisites, or recommended context, so an agent must infer usage solely from the name and one-line description.

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