UK solar PV and heat pump calculators that follow the published MCS methods. Open, no key.
Scored across 12 tools
Each calculator has a distinct primary purpose and the descriptions explicitly cross-reference related tools, such as solar_pv_output versus solar_pv_system_size. The main overlap is heat_pump_size, which also reports running-cost comparisons, alongside the dedicated heat_pump_running_cost tool, so an agent could occasionally hesitate between them.
All tool names use clear snake_case, with consistent domain prefixes such as heat_pump_ and solar_pv_ for related calculators. The only verb-first meta tool, list_calculators, is still predictable and does not disrupt the overall naming pattern.
Twelve tools is well-scoped for a multi-domain calculator server, covering solar PV, heat pumps, and connection routing without obvious filler. Each calculator appears to earn its place, and list_calculators adds useful discovery/reference capability.
The surface covers the full calculation chain for solar PV sizing, output, shading, and self-consumption, as well as heat pump sizing, room heat loss, emitter temperature, hot water, noise, and running cost. Connection routing and a reference-data listing complete the domain without obvious dead ends.
Work out which ENA connection procedure a domestic installation of solar panels, batteries or both falls under: connect first and notify the distribution network operator within 28 days, or apply and wait for approval before anything is connected.
The rules are the ENA's engineering recommendations, not MCS documents: EREC G98 for small installations, EREC G99 for everything larger, and EREC G100 for export limitation. Every test is in amps per phase at a nominal 230 V, and it applies to the premises as a whole, so list EVERY inverter that can export, existing ones included. A battery counts as generation even if it only ever charges from the panels.
The figure that counts is each inverter's registered capacity: its AC rating, or a lower limit the manufacturer has fixed. It is NOT the panels' kWp. A 4.4 kWp array on a 3.68 kW inverter is a 3.68 kW installation. Where an inverter has been capped below its hardware rating, give the hardware rating as 'designCapacityKw', because G99 tests that separately.
The routes are: G98 when the total is 16 A per phase or less (3.68 kW single phase, 11.04 kW three phase); G99 SGI-1, also connect and notify, when the total is within 16 A but an inverter built for up to 32 A has been capped; G99 SGI-2 and SGI-3, fast track applications answered within 10 working days, which allow larger totals held back by a type-tested export limiter; and the standard G99 application for anything else. An export limiter NEVER brings an installation under G98.
IMPORTANT: this says which procedure applies, not what the operator will decide. Approval depends on the local network, which only the operator can assess. Say so whenever you report a result.
Method from EREC G98 / G99. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| phases | No | The supply: 1 for single phase, which is almost every British house, or 3 for three phase. Defaults to 1. | |
| devices | Yes | Every inverter at the premises that can export: solar, battery and hybrid, existing ones included. A battery counts even if it only charges from the panels. At least one is required. | |
| exportLimitKw | No | The export limit a fully type-tested G100 scheme would hold the premises to, in kW per phase, where one is proposed. Optional. An export limit never brings an installation under G98, but it decides which G99 route applies. | |
| otherInstallationsNearby | No | True when the same installer has fitted, or plans to fit, generation at other premises within 500 metres, or on the same street, within 28 days either side. That turns a G98 notification into an application. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| route | Yes | |
| method | Yes | |
| phases | Yes | Registered capacity on each phase, in kW and in amps at the nominal 230 V the recommendations use. |
| devices | Yes | |
| totalKw | Yes | Registered capacity of every device added together. |
| verdict | Yes | |
| warning | Yes | Which route applies is arithmetic; what the network operator decides is not. Always present. |
| g98LimitKw | Yes | 16 A per phase at 230 V: 3.68 kW on a single phase supply, 11.04 kW on three phase. |
| references | Yes | |
| worstPhaseA | Yes | Current on the most heavily loaded phase. This is the figure the thresholds are tested against. |
| alternatives | No | Changes that would put the installation on an easier route, and what each would cost. |
| exportLimitA | No | The proposed export limit converted to amps per phase. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses crucial behavioural limits: this only says which procedure applies, not what the operator will decide, and the operator alone can assess the local network. It also flags that results are advisory for understanding/checking quotes and that installation still requires design and site survey from a certified installer.
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?
Purpose is front-loaded and the dense regulatory content is mostly load-bearing, but it runs to five paragraphs and repeats the export-limiter caveat already present in the exportLimitKw schema description. Slightly long, yet nearly every sentence earns its place in a rule-heavy domain.
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 values need no explanation. With that covered, the description supplies the method basis (EREC G98/G99/G100, MCS), the routing thresholds, and the advisory caveat, leaving nothing an agent needs to call and report results 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?
Schema coverage is already 100%, so baseline is 3, but the description adds genuine interpretive meaning: registered capacity (inverter AC rating, not panels' kWp), designCapacityKw for capped inverters because G99 tests it separately, counting existing devices and batteries as generation, and the 16 A / 28-day / 500 m rules that give the parameters operational meaning.
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 opening sentence names a specific verb ('Work out which ... procedure') and resource (ENA connection procedure for domestic solar/battery installations). It cleanly distinguishes this routing/regulatory tool from the sibling calculators (solar_pv_output, heat_pump_size, etc.) that compute physical quantities.
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 states the input context clearly (domestic installations of solar panels, batteries or both) and explains the decision it drives (connect-and-notify vs apply-first). It does not name an alternative sibling or state when NOT to use it, but there is no near-duplicate sibling to disambiguate against, so the guidance is effectively complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the sound pressure level an air source heat pump produces at an assessment position, and whether it meets the 37 dB(A) permitted development noise limit, using the method in MCS 020.
The formula is Lp = Lw + 10 log(Q / 4.pi.r^2) - Ab.
Lw is the A-weighted sound POWER level of the unit from its product fiche, energy label or the MCS product database. This is not the sound pressure level, which is a smaller number that already has a distance built into it; confusing the two produces an answer that is wrong by about twenty decibels. The figure for low noise mode must not be used.
Q is the directivity factor, from the count of reflecting surfaces within one metre of the unit that extend at least a metre past it in two or more directions. The ground counts; vegetation does not. One surface gives Q=2, two gives Q=4, three gives Q=8. More than three cannot meet MCS 020 at all.
r is the straight-line distance in metres to the assessment position, which is a window or door of a habitable room in a NEIGHBOURING property, at any floor. Every affected position must be checked separately, and the nearest is not always the worst.
Ab is the barrier attenuation. Fences with gaps, and vegetation of any kind, count as no barrier.
Where several units serve one position, list them all and they are combined logarithmically.
Method from MCS 020. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| units | Yes | The heat pump or heat pumps being assessed, each with its own distance and barrier to this assessment position. At least one is required. |
| Name | Required | Description |
|---|---|---|
| limit | Yes | The permitted development noise limit, 37.0 dB(A). |
| notes | Yes | |
| units | Yes | |
| method | Yes | |
| verdict | Yes | |
| headroom | Yes | Decibels below the limit. Negative when the limit is exceeded. |
| remedies | No | What would bring a failing position within the limit. |
| compliant | Yes | True when the level is at or below the limit. |
| references | Yes | |
| soundPressureLevel | Yes | Combined A-weighted sound pressure level at the assessment position, in dB(A), rounded to one decimal place as MCS 020 requires. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description discloses genuine behavioral constraints: more than three reflecting surfaces 'cannot meet MCS 020 at all', low-noise-mode figures must not be used, and mistaking Lw for Lp is off by ~20 dB. That is useful failure-mode context, though it stops short of stating assumptions or limitations of the calculation itself.
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?
Front-loaded purpose sentence, then one short paragraph per formula term, then a scope disclaimer. Long but every section maps to a decision the caller must make (which Lw, which Q, which r, which Ab), and nothing is padding.
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 not be explained. The description supplies the method, the multi-unit combination rule, the pass/fail constraint, and the professional-advice caveat, leaving no gap an agent needs filled before calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3; the description earns above baseline by explaining the concepts behind each field (directivity factor Q from reflecting surfaces, r as straight-line distance to a neighbouring habitable room, Ab as barrier attenuation where gaps/vegetation count as none) and by warning about the most common input error.
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 ('Calculate the sound pressure level an air source heat pump produces at an assessment position') plus the regulatory test it performs (37 dB(A) permitted development limit, MCS 020). This is unambiguous and clearly distinct from siblings like heat_pump_size or heat_pump_running_cost.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives real operational guidance: 'Every affected position must be checked separately', 'the nearest is not always the worst', and multi-unit handling ('list them all and they are combined logarithmically'). It frames the tool for 'understanding a system and checking a quotation', but never names an alternative tool or states when not to use this one, so it stops 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.
Compare what a household spends heating on its current fuel with what the same heat would cost from a heat pump.
The heat demand is worked out from the household's own metered fuel use, not from a model, because a year of bills describes a particular house far better than any estimate of it. Supply the annual fuel use in the fuel's own unit (kWh for gas and electricity, litres for oil and LPG, kilograms for coal), its price per unit in pounds, and the seasonal efficiency of the existing appliance, which defaults to a realistic figure for that fuel instead of the one on the badge.
The comparison turns on one ratio. A heat pump costs less to run whenever its seasonal coefficient of performance beats the ratio between the price of a unit of electricity and the price of a unit of heat from the current fuel. The result reports that break-even figure explicitly.
SCOP must be the figure at the flow temperature the system is actually designed for. The same machine can return 4.2 at 35 degrees and 3.1 at 55, and quoting the first for a system designed at the second is the commonest way of overstating a saving.
This is a running cost comparison. It says nothing about the capital cost or any grant.
Method from MCS 007. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| fuel | No | The fuel being replaced: 'mains_gas', 'oil', 'lpg', 'electricity' or 'coal'. Defaults to 'mains_gas'. | |
| scop | Yes | Seasonal coefficient of performance of the proposed heat pump: the units of heat it delivers per unit of electricity, averaged over a year at the design flow temperature. Required. | |
| annualFuelUse | Yes | How much of that fuel the house uses in a year, in the fuel's own unit: kWh for gas and electricity, litres for oil and LPG, kilograms for coal. Take it from a year of bills. Required. | |
| fuelPricePerUnit | Yes | Price of one unit of that fuel, in pounds. Required. | |
| nonHeatingFraction | No | Share of that fuel used for something other than heating and hot water, such as a gas hob, as a decimal. A hob is usually 0.03 to 0.05. Defaults to 0. | |
| applianceEfficiency | No | Seasonal efficiency of the existing appliance, as a decimal. Defaults to the typical figure for the fuel. | |
| electricityPricePerKwh | Yes | Price of a unit of electricity, in pounds. Required. | |
| fuelStandingChargePerDay | No | Daily standing charge for that fuel in pounds, if it has one. A house that removes its gas boiler can usually stop paying this. | |
| electricityStandingChargePerDay | No | Daily electricity standing charge in pounds. It is paid either way, so it only changes the answer if the tariff changes with the heat pump. |
| Name | Required | Description |
|---|---|---|
| fuel | Yes | |
| scop | Yes | |
| notes | Yes | |
| method | Yes | |
| verdict | Yes | |
| references | Yes | |
| breakEvenScop | Yes | The seasonal efficiency at which the heat pump costs exactly what the current system costs. Below this it costs more. |
| annualDifference | Yes | Positive when the heat pump costs less. |
| costPerKwhHeatNow | Yes | What a unit of delivered heat costs today, in pounds. |
| currentAnnualCost | Yes | |
| percentDifference | Yes | |
| heatPumpAnnualCost | Yes | |
| annualHeatDemandKwh | Yes | Useful heat the house actually needs in a year, after the existing appliance's losses are taken off its fuel input. |
| applianceEfficiency | Yes | |
| breakEvenPriceRatio | Yes | How many times dearer a unit of electricity is than a unit of the current fuel. Compare it with the SCOP: a heat pump saves money whenever the SCOP beats this ratio. |
| costPerKwhHeatHeatPump | Yes | What a unit of delivered heat would cost from the heat pump. |
| heatPumpElectricityKwh | Yes | Units of electricity the heat pump would use in a year. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds real behavior beyond them: the method comes from MCS 007, the result reports the break-even ratio, and it flags what the tool does NOT model (capital cost, grants). It could go further on output shape, though the output schema carries 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?
Front-loaded with the comparison, then inputs, then the break-even logic and the SCOP caveat, then scope/method. Four paragraphs is on the long side, but the SCOP and break-even sentences earn their place by preventing common errors.
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 9-parameter calculator with an output schema and full annotation coverage, the description supplies the domain framing, methodological provenance, and limitations an agent needs. Return values are correctly left to the 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?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: units per fuel type, that appliance efficiency defaults to a realistic figure not the badge value, and the critical caveat that SCOP must reflect the design flow temperature. That is meaningful context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific comparison: what a household spends on its current fuel versus what the same heat would cost from a heat pump. It is immediately distinguishable from siblings like heat_pump_size or heat_pump_noise, and it explicitly scopes itself as running cost only, excluding capital cost and grants.
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 explains the intended context (understanding a system, checking a quotation) and warns that anything installed still needs a design and site survey. It does not name a sibling tool or an alternative for capital-cost questions, but the 'when to use' context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the heat pump a UK house needs, and what it would cost to run against the fuel it burns now.
IMPORTANT: MIS 3005-D requires a heat pump to be sized from a room-by-room heat loss calculation to BS EN 12831, and nothing here replaces that. Say so whenever you report a result from this, and point the user at the room-by-room calculation. What the figure is for is checking whether a size somebody has been quoted is plausible, because oversizing is the commonest fault in heat pump installations and it is invisible to the person living with it.
There are two routes and the first is much the better one.
From metered fuel, which is preferred: give 'annualFuelUse' from a year of bills. The fuel becomes heat delivered, hot water comes off it using the MIS 3005-D formula, and what remains divided by the local heating degree days gives the building's heat loss coefficient in watts per kelvin. Degree days are computed from the Met Office monthly means published in MGD 007 section 5.
From the fabric, as a fallback when there are no bills: give 'floorAreaM2', an 'insulation' level and a 'propertyType'. The watts per kelvin per square metre behind this are a reasonable reading of British housing stock but they are NOT MCS figures, because MCS publishes no such shortcut. Say so when using this route.
Either way the peak load is the coefficient multiplied by the design temperature difference for the location, from Table 2 of MIS 3005-D. The heat pump must deliver at least that at the design outside temperature and the design flow temperature, which is not the same as its headline rating.
The result also compares what each of four flow temperatures would cost to run, which is the decision that governs the bill and the one a quotation most often leaves unstated. Supply 'quotedHeatPumpKw' to have a quoted size checked against the estimate.
Method from MIS 3005-D. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| fuel | No | The fuel the house is heated with now: 'mains_gas', 'oil', 'lpg', 'electricity' or 'coal'. Defaults to 'mains_gas'. | |
| scop | No | Seasonal coefficient of performance of the proposed heat pump, if it is known from the MCS Product Directory. Defaults to an indicative figure for the chosen flow temperature. | |
| bedrooms | No | Number of bedrooms, for the hot water demand. Defaults to 3. | |
| location | Yes | Nearest of the eight tabulated locations: 'belfast', 'birmingham', 'cardiff', 'edinburgh', 'glasgow', 'london', 'manchester' or 'plymouth'. Required. | |
| occupants | No | Number of people living there, if known. MIS 3005-D takes the greater of this and bedrooms plus one. | |
| insulation | No | How well insulated the building is: 'solid', 'cavity_unfilled', 'insulated', 'modern' or 'very_efficient'. Used only with floorAreaM2. | |
| designBasis | No | 'a' for the 99% outside design temperature or 'b' for the colder 99.6% one. Defaults to 'a'. | |
| floorAreaM2 | No | Total heated floor area in square metres, over all storeys. Used only when no fuel figure is given. | |
| internalTemp | No | Whole-house mean internal design temperature in Celsius. Defaults to 20, which is a reasonable average of the room-by-room figures in MIS 3005-D Table 1. | |
| propertyType | No | 'detached', 'semi', 'end_terrace', 'mid_terrace', 'flat' or 'bungalow'. Used only with floorAreaM2. Defaults to 'semi'. | |
| annualFuelUse | No | How much of that fuel the house burns in a year, in its own unit: kWh for gas and electricity, litres for oil and LPG, kilograms for coal. Give this if it is known: it describes the actual house and is far better than the fabric estimate. | |
| flowTemperature | No | The flow temperature the system would be designed around: 35, 45, 50 or 55. Defaults to 45. This is the single biggest influence on running cost. | |
| fuelPricePerUnit | No | Price of one unit of the current fuel, in pounds. Optional; supplying it and the electricity price gives a running cost comparison. | |
| quotedHeatPumpKw | No | The output of a heat pump somebody has quoted, in kW. Optional; supplying it says whether that size looks plausible against this estimate. | |
| nonHeatingFraction | No | Share of that fuel used for something other than heating and hot water, such as a gas hob, as a decimal. A hob is usually 0.03 to 0.05. Defaults to 0. | |
| summerMonthFuelUse | No | Fuel used in a single summer month, in the same unit, when the heating is off. Give this if it can be found: almost all of it is hot water, so it separates hot water from space heating exactly and removes the biggest assumption in the estimate. | |
| applianceEfficiency | No | Seasonal efficiency of the existing boiler as a decimal. Defaults to a realistic figure for the fuel instead of the one on the badge. | |
| electricityPricePerKwh | No | Price of a unit of electricity, in pounds. Optional. |
| Name | Required | Description |
|---|---|---|
| scop | Yes | |
| basis | Yes | |
| notes | Yes | |
| method | Yes | |
| warning | Yes | |
| location | Yes | |
| basisNote | Yes | |
| references | Yes | |
| designBasis | Yes | |
| scopAssumed | Yes | True when an indicative figure stood in for a real one from the product directory. |
| internalTemp | Yes | |
| breakEvenScop | No | The seasonal efficiency at which the two cost the same. |
| peakHeatLossKw | Yes | The space heating load at the design outside temperature. The heat pump must deliver at least this, at the design flow temperature, without help from an immersion heater. |
| flowTemperature | Yes | |
| quotedSizeCheck | No | |
| annualDifference | No | Positive when the heat pump costs less. |
| annualHotWaterKwh | Yes | |
| currentAnnualCost | No | |
| heatingDegreeDays | Yes | |
| externalDesignTemp | Yes | |
| heatPumpAnnualCost | No | |
| annualHeatDemandKwh | Yes | |
| dailyHotWaterLitres | Yes | |
| wattsPerSquareMetre | No | Peak load per square metre of floor, where a floor area was given. A useful sanity check. |
| flowTemperatureCosts | No | |
| annualSpaceHeatingKwh | Yes | |
| hotWaterFromSummerUse | Yes | True when a summer month's fuel separated hot water from space heating, instead of an allowance standing in for it. |
| temperatureDifference | Yes | |
| heatPumpElectricityKwh | Yes | |
| heatLossCoefficientWPerK | Yes | How many watts the building loses for every degree between inside and outside. The figure everything else follows from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond that: method provenance (MIS 3005-D, BS EN 12831, MGD 007 section 5), the compliance caveat that nothing here replaces a room-by-room calculation, and the behavioural note that peak load differs from a heat pump's headline rating.
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?
Long, but the length is largely justified for an 18-parameter tool with a regulatory dimension. Purpose is front-loaded, then caveats, then the two routes. Some sentences (repeated MIS 3005-D sourcing) could be tightened, keeping it just short of 5.
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 return values needn't be described, freeing the description to cover method, caveats and routing — which it does thoroughly. For a complex, high-stakes calculator an agent has everything needed to call it correctly and to report results honestly.
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 all 18 parameters and the baseline is 3. The description adds real meaning on top: it explains the two interaction routes (which parameters pair with which), why annualFuelUse is 'far better' than the fabric route, and what summerMonthFuelUse buys (isolating hot water).
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: 'Estimate the heat pump a UK house needs, and what it would cost to run against the fuel it burns now.' It also distinguishes itself from siblings by explicitly routing the agent to the room-by-room heat loss calculation rather than doing it here, which separates it from room_heat_loss.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing: the metered-fuel route is 'much the better one', the fabric route is a fallback 'when there are no bills', and quotedHeatPumpKw is for checking a quotation. It also states when to caveat results (MIS 3005-D compliance) and warns the fabric route is not MCS figures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work out the daily hot water demand of a dwelling and the size of cylinder a heat pump needs, using the formula in MIS 3005-D 3.5.2 and the BS 6700 guidance reproduced in MGD 007.
The demand is 45 litres a day for each of N, where N is the greater of the number of bedrooms plus one and the number of people actually living there. For a new build, where occupancy is unknown, the bedroom count is used.
The cylinder does not have to hold a whole day's demand, because it reheats as it empties. What it must cover is the largest draw-off before the heat pump catches up, which is why a larger heat pump needs a smaller cylinder: reheat time is volume times temperature rise, divided by 14.3 times the kW.
The result gives the BS 6700 minimum, a recommended size rounded to a volume cylinders are made in, and the reheat time. Note that cylinder volume is not the whole story: a heat pump cylinder needs a much larger coil than a boiler cylinder, because the water arrives cooler and there is less temperature difference to drive heat across the surface.
Method from MIS 3005-D. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| bedrooms | Yes | Number of bedrooms in the property. Required. | |
| bathrooms | No | Number of bathrooms with a bath. Defaults to 1. | |
| occupants | No | Number of people who actually live there, if known. MIS 3005-D takes the greater of this and bedrooms plus one. Leave it out for a new build, where the occupancy is not yet known. | |
| storageTemp | No | Temperature the cylinder is stored at, in Celsius. Defaults to 55, which is a common heat pump setting. A weekly pasteurisation cycle above 60 is separate. | |
| coldWaterTemp | No | Incoming mains temperature in Celsius. Defaults to 10. | |
| heatPumpOutputKw | No | Heat output of the heat pump in kW when it is heating the cylinder. A larger heat pump reheats faster, so it needs less stored volume. Defaults to 6. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| method | Yes | |
| bedrooms | Yes | |
| bathrooms | Yes | |
| occupants | No | |
| references | Yes | |
| storageTemp | Yes | |
| coldWaterTemp | Yes | |
| reheatMinutes | Yes | Roughly how long the heat pump takes to bring the whole cylinder up from cold, ignoring standing losses. |
| occupancyBasis | Yes | Which of the two gave the larger figure. |
| designOccupancy | Yes | N in the MIS 3005-D formula: the greater of bedrooms plus one and the known occupants. |
| energyPerDayKwh | Yes | Heat needed each day to raise the daily demand from mains temperature to storage temperature. |
| heatPumpOutputKw | Yes | |
| dailyDemandLitres | Yes | Average daily hot water demand: 45 litres for each of N. |
| minimumCylinderLitres | Yes | The BS 6700 minimum for this number of bathrooms and this heat pump output, before the allowance MGD 007 adds for extra bathing capacity. |
| recommendedCylinderLitres | Yes | Cylinder volume from the BS 6700 guidance in MGD 007, given the number of baths and the heat pump output. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish a safe, idempotent, closed-world read, and the description goes well beyond them: it states what the result contains (BS 6700 minimum, a rounded recommended size, reheat time), the 45 l/person/day basis, the reheat formula (volume x temp rise / 14.3 x kW), and the counterintuitive coil-sizing caveat. 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?
Front-loaded with purpose and method, then the occupancy rule, the reheat logic, and the outputs, so an agent gets the essentials first. It runs long, though; the coil-versus-boiler paragraph is educational context rather than something needed to call the tool correctly.
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 six parameters, an output schema present, and full schema coverage, the description supplies everything else an agent needs: method provenance, the occupancy fallback for new builds, the formula dependencies, and the advisory caveat. Return values are covered by the output schema and echoed usefully here.
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 genuinely adds meaning the schema lacks: the 45 litre daily multiplier behind 'N', the explicit statement that a larger heat pump yields a smaller cylinder, and the reheat-time relationship touching kW, storage and cold-water temperatures. It does not restate parameter syntax, which is fine given the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and dual resource: working out a dwelling's daily hot water demand and the cylinder size a heat pump needs. It also cites the governing method (MIS 3005-D 3.5.2, BS 6700/MGD 007), which cleanly separates it from siblings like heat_pump_size and room_heat_loss.
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 frames the tool as 'for understanding a system and checking a quotation' and warns that installed work still requires a certified installer's design and survey, which tells the agent the outputs are advisory not prescriptive. It gives the condition for switching input basis (new build → bedroom count), but never names a sibling tool or an explicit when-not-to-use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every calculator on this server, with the standard behind it and whether it is the whole-system sizing calculator or one of the single-method ones, plus the reference data a caller needs to build a valid request: the compass directions and their orientations, the shading descriptions, the twenty-five solar postcode zones, the eight heat pump design locations with their design temperatures, the room types and their internal design temperatures, the heat loss element kinds, the occupancy archetypes and the fuel types. Call this when a value must be one of a fixed set and you are not sure what the set is.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| notice | Yes | |
| reference | Yes | |
| calculators | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by enumerating exactly which reference sets are returned (directions, shading, 25 postcode zones, 8 heat pump locations, etc.), which is more than the annotations convey.
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 core purpose is front-loaded in the opening clause, and the enumeration of reference sets is genuinely useful for a discovery tool. However, the single run-on sentence packing ten-plus data categories alongside the calculator-type aside is denser than it needs to be for easy scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return format need not be explained, yet the description still previews the contents the agent will get. For a zero-parameter, read-only discovery tool, nothing an agent needs in order to call it correctly 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?
The tool takes zero parameters, so there is no parameter semantics to document; per the rubric this yields the baseline of 4. The description correctly does not invent parameter behavior.
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 ('Lists every calculator on this server') and goes further by categorizing the two calculator kinds (whole-system sizing vs single-method). An agent can distinguish this discovery tool from the dozen sibling calculators that each perform one calculation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete trigger: 'Call this when a value must be one of a fixed set and you are not sure what the set is.' That implies the alternative is to call a specific sibling directly when you already know the required values, but no sibling is named explicitly, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work out the flow temperature a heat pump must produce to heat a room through a given radiator, and the resulting MCS Heat Emitter Guide star rating, following section 4 of MGD 007.
This is the calculation that decides whether a heat pump will be cheap or expensive to run. A heat pump's efficiency falls as the water temperature rises, by roughly two to three per cent per degree, and the temperature it must produce is set by the radiators, not by the machine.
Supply the room's design heat loss in watts, from a room-by-room calculation, and the rated output of the radiator in that room. British catalogues normally quote at a mean-water-to-air difference of 50 K; if yours quotes 60, say so and the figure is restated.
The result gives the oversize factor, which is the radiator's output at 50 K divided by the room's heat loss, and converts it to a required flow temperature through the BS EN 442 output law. Star ratings run from 0 to 6, one star per five degrees of flow temperature, with six stars at 35 degrees.
Run this for every room. A house runs at the flow temperature its worst room demands, so one undersized radiator sets the running cost for the whole house.
Method from MGD 007. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| roomTemp | No | Internal design temperature of the room in Celsius. Defaults to 21. | |
| systemDeltaT | No | Designed drop in water temperature between flow and return, in kelvin. Heat pump systems commonly use 5; boiler systems used 10 or 20. Defaults to 5. | |
| ratedAtDeltaT | No | The mean-water-to-air temperature difference the rated output was quoted at. British catalogues normally quote 50; some older ones quote 60. Defaults to 50. | |
| roomHeatLossW | Yes | The room's design heat loss in watts, from a room-by-room heat loss calculation. Required. | |
| radiatorOutputW | Yes | Rated output of the radiator or radiators in that room, in watts, at the catalogue temperature. Required. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| method | Yes | |
| verdict | Yes | |
| references | Yes | |
| starRating | Yes | Temperature star rating from the MCS Heat Emitter Guide, 0 to 6. More stars mean a lower flow temperature and a more efficient system. |
| meanWaterTemp | Yes | Average of flow and return temperature needed to deliver the room's heat loss through this radiator. |
| ratedAtDeltaT | Yes | |
| roomHeatLossW | Yes | |
| oversizeFactor | Yes | Radiator output at 50 K divided by the room's heat loss. The single number the Heat Emitter Guide turns into a star rating. |
| flowTemperature | Yes | The flow temperature the heat pump must produce, in Celsius. |
| radiatorOutputW | Yes | |
| starRatingLabel | Yes | |
| outputAtDeltaT50 | Yes | The radiator's output restated at a mean-water-to-air difference of 50 K, so oversize factors are comparable between catalogues. |
| returnTemperature | Yes | |
| outputAtDesignFlowW | Yes | What this radiator actually gives at the flow temperature worked out here. |
| radiatorOutputForFiveStarsW | Yes | The radiator output at 50 K that would reach a five star rating, meaning a 40 degree flow temperature. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive and closed-world, so safety is covered. Beyond that the description discloses genuine behaviour: the 60 K catalogue convention triggers a restatement of the figure, the result yields an oversize factor converted via the BS EN 442 output law, and star ratings map 0-6 with one star per five degrees. It adds context annotations cannot 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?
The purpose and inputs are front-loaded and the paragraph order (what it does, why it matters, what to supply, what you get, how to apply it, provenance) is logical. It is slightly long: the tutorial on heat pump efficiency falling two-to-three per cent per degree is useful interpretation context but not needed to invoke the tool.
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 values need not be explained, yet the description still summarises the key outputs (oversize factor, required flow temperature, star rating). Combined with input guidance, the per-room instruction, and the installation disclaimer, it covers what an agent needs; only explicit error or boundary behaviour is unaddressed.
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 schema already documents all five parameters including the 50 K vs 60 K catalogue convention and defaults. The description largely restates this, adding only the behavioural detail that a 60 K input causes the figure to be restated; that is helpful but marginal, 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 description names a specific verb and resource ('work out the flow temperature a heat pump must produce ... through a given radiator') plus the secondary output (MCS Heat Emitter Guide star rating) and the governing method (MGD 007 section 4). This clearly separates it from siblings like heat_pump_size or room_heat_loss, which supply inputs rather than this calculation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives strong workflow context: 'Supply the room's design heat loss in watts, from a room-by-room calculation', 'Run this for every room', and 'one undersized radiator sets the running cost for the whole house'. It also frames the tool as for understanding/checking a quotation rather than certified design. It does not explicitly name an alternative tool or a when-not-to-use condition, so it falls 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.
Calculate the design heat loss of a single room in watts, following BS EN 12831 as MIS 3005-D applies it. This is the figure a heat pump is sized from and the figure the radiator in that room must be able to deliver.
BS EN 12831 is a room-by-room method. Run this once for each heated room and add the results; sizing a heat pump from floor area alone is what produces the oversized installations that cycle all winter.
Internal design temperatures come from Table 1 of MIS 3005-D and follow from the room type: 22 for a bathroom, 21 for living and dining rooms, 18 for bedrooms, halls, kitchens and toilets. These are minimums, so a higher figure is accepted and a lower one is refused.
External design temperatures come from Table 2, for eight locations, in two columns: 'a' is the 99% figure and 'b' the colder 99.6% one, which needs no uplift for intermittent heating.
Each element needs an area, a U-value, and a kind. The kind matters because it fixes which temperature difference applies. Walls, windows, doors, roofs and suspended floors lose heat to the outside design temperature. A SOLID FLOOR ON THE GROUND loses heat to the local annual average air temperature instead, which is far warmer, and getting this wrong is the commonest error in a heat loss calculation. Window and door areas belong to the window and the door, not to the wall behind them.
Method from MIS 3005-D. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| elements | Yes | Every surface through which the room loses heat. At least one is required. | |
| location | Yes | Which of the eight tabulated locations the property is nearest: 'belfast', 'birmingham', 'cardiff', 'edinburgh', 'glasgow', 'london', 'manchester' or 'plymouth'. Required. | |
| roomName | No | A name for the room. | |
| roomType | No | Which of the tabulated room types this is: 'living_room', 'dining_room', 'bedsitting_room', 'bathroom', 'bedroom', 'kitchen', 'hall' or 'toilet'. Sets the internal design temperature. Defaults to 'living_room'. | |
| designBasis | No | 'a' for the 99% outside design temperature or 'b' for the colder 99.6% figure. Column B needs no uplift for intermittent heating. Defaults to 'a'. | |
| floorAreaM2 | Yes | Floor area of the room in square metres. Required, and used with the ceiling height to work out the ventilation loss. | |
| internalTemp | No | Internal design temperature in Celsius, if it should differ from the tabulated value for the room type. MIS 3005-D sets the tabulated values as a floor, not a target, so a higher figure is allowed and a lower one is not. | |
| ceilingHeightM | No | Floor to ceiling height in metres. Defaults to 2.4. | |
| airChangesPerHour | No | How many times an hour the air in the room is replaced. A draughty old room may be 1.5 or more; a well sealed new one 0.5. Defaults to 1. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| method | Yes | |
| elements | Yes | |
| location | Yes | |
| roomName | No | |
| roomType | Yes | |
| references | Yes | |
| designBasis | Yes | |
| fabricLossW | Yes | |
| largestLoss | No | Which single element loses most, which is where insulating first pays best. |
| internalTemp | Yes | |
| roomVolumeM3 | Yes | |
| totalHeatLossW | Yes | The room's design heat loss in watts. This is what the emitter in the room has to deliver on the coldest day. |
| ventilationLossW | Yes | |
| externalDesignTemp | Yes | |
| fabricSharePercent | Yes | |
| wattsPerSquareMetre | Yes | Heat loss divided by floor area. A useful sanity check: a well insulated room lands near 40, a poor one well over 100. |
| temperatureDifference | Yes | Internal minus external design temperature, in kelvin. The figure most of the fabric loss is worked out against. |
| ventilationSharePercent | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly, idempotent), and the description goes well beyond them: documented defaults, the rule that tabulated internal temps are a floor (lower refused), the ground-floor-vs-suspended-floor temperature distinction, and the explicit limits of the tool ('for understanding a system and checking a quotation'). That is exactly the behavioral context the annotations cannot 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?
Purpose and scope are front-loaded, which is good, but the text runs four paragraphs with repetition (BS EN 12831 and MIS 3005-D each cited multiple times) and ends on a boilerplate installer disclaimer that does not help an agent call the tool. For a 9-parameter calculator some length is justified, yet trimming is possible.
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 values need no explanation, and the description compensates for the remaining complexity: defaults, temperature-source tables, element-kind semantics, and the commonest-error warning about solid floors. Nothing an agent needs to invoke it correctly 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 coverage is 100%, so the baseline is 3; the description adds genuine meaning on top, explaining that 'kind' fixes which temperature difference applies, why ground_floor is special, and how roomType maps to design temperatures. It reinforces the schema rather than merely restating 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?
States a specific verb and resource ('Calculate the design heat loss of a single room in watts') and pins the method (BS EN 12831 as MIS 3005-D applies it). The scope word 'single room' cleanly separates it from the aggregate sibling heat_pump_size.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives real usage context — 'run this once for each heated room and add the results' and warns against sizing a heat pump from floor area alone, which implies the sibling relation to heat_pump_size. It stops short of naming the sibling tool or stating explicit when-not-to-use rules, so it is clear context without full routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the annual AC electricity output of a UK solar photovoltaic system, in kWh, using the standard estimation method that MIS 3002 requires every MCS certified installer to use.
The method is: annual output = kWp x Kk x SF, where Kk is read from the MCS irradiance dataset for the site's postcode zone, roof pitch and orientation, and SF is a shade factor between 0 and 1.
Supply the postcode and the array's capacity in kWp, plus the roof's pitch in degrees from horizontal and its orientation in degrees away from due south in either direction, so that south is 0, south-east and south-west are both 45, east and west are both 90, and north is 180.
The result carries the tabulated yield, the estimate, and what the same array would produce at the best pitch and orientation for that zone, so a roof that is merely good is not mistaken for a poor one. This covers the United Kingdom only; the dataset has no values for anywhere else.
Method from MIS 3002. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| zone | No | MCS postcode zone code, for example '5E'. An alternative to 'postcode' when the zone is already known. | |
| postcode | No | UK postcode of the installation, for example 'BS1 5TR'. Only the outward code matters. Give this or 'zone'. | |
| capacityKwp | Yes | Total installed capacity in kilowatts peak: the sum of the nameplate watts of every module, divided by 1000. Required. | |
| inclination | Yes | Pitch of the array in degrees from horizontal. A flat roof is 0 and a wall-mounted array is 90. Required. | |
| orientation | Yes | Degrees the array faces away from due south, in either direction, so due south is 0, south-east and south-west are 45, east and west are 90, and due north is 180. Required. | |
| shadeFactor | No | Proportion of output left after shading, between 0.5 and 1. Use 1 for a clear horizon. Defaults to 1. |
| Name | Required | Description |
|---|---|---|
| zone | Yes | |
| notes | Yes | |
| method | Yes | |
| references | Yes | |
| capacityKwp | Yes | |
| inclination | Yes | Inclination after rounding to the nearest degree, as the method requires. |
| orientation | Yes | Orientation after rounding to the nearest five degrees, as the method requires. |
| shadeFactor | Yes | |
| postcodeUsed | No | The postcode the zone was resolved from, when one was given. |
| shadingLossKwh | Yes | |
| annualOutputKwh | Yes | The estimate: capacity multiplied by Kk multiplied by the shade factor. |
| bestCaseAnnualKwh | Yes | What this capacity would produce at the best pitch and orientation for the zone, unshaded. A yardstick, not a target: a roof faces where it faces. |
| percentOfBestCase | Yes | The estimate as a percentage of that best case. |
| unshadedOutputKwh | Yes | What the same array would produce with a clear horizon. Equals the estimate when the shade factor is 1. |
| bestCaseInclination | Yes | The pitch that yields most at this zone when facing due south. |
| bestCaseOrientation | Yes | The orientation that yields most at this pitch and zone. Almost always due south. |
| specificYieldKwhPerKwp | Yes | Kk: the kWh a single kWp produces in a year at this zone, pitch and orientation, before shading. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly, idempotent and non-destructive, and the description is consistent with openWorldHint=false by stating the tool covers the United Kingdom only and that the dataset has no values elsewhere — a genuinely useful scope limit. It also discloses what the result carries (tabulated yield, the estimate, and the best-pitch/orientation comparison for the zone), which goes beyond annotations, though it says nothing about precision, tolerance or failure modes.
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?
Front-loaded: the first sentence states the estimate and the unit, and the formula and input conventions follow in a logical order. It runs long — the formula, the orientation convention and the best-orientation rationale each get substantial space — but almost every sentence carries information an agent needs, and the padding is limited to the MIS 3002 framing and the closing caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter estimator with a full output schema and complete input annotations, the description covers method, required inputs, geographic scope and output contents, so an agent can invoke it without guessing. The notable remaining gap is explicit routing against the neighbouring solar tools, which the description never addresses.
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 per-parameter baseline is 3; the description slightly exceeds that by exposing the calculation the parameters feed (annual output = kWp × Kk × SF) and by explaining that Kk is derived from the postcode zone combined with pitch and orientation. It largely restates the orientation and shade-factor conventions already in the schema, so the added value is modest rather than decisive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a precise verb and resource — 'Estimate the annual AC electricity output of a UK solar photovoltaic system, in kWh' — and names the governing method (MIS 3002 / MCS). The sibling set contains several similarly named solar tools (solar_pv_shading, solar_pv_system_size, solar_pv_self_consumption), and the stated output resource is distinct enough to separate this one from 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?
It supplies clear usage context ('for understanding a system and checking a quotation') and a boundary ('Anything that gets installed still needs a design and a site survey from a certified installer'), which tells the agent this is advisory, not a final design. It does not, however, explicitly say when to call solar_pv_shading or solar_pv_system_size instead, so the alternative routing is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate what proportion of a domestic solar PV system's annual output is consumed in the house and what proportion is exported, using the lookup tables in MGD 003.
The tables are not a model. They come from half-hourly monitoring of real British households by Loughborough University, with battery behaviour modelled on top, so they carry the real shape of domestic demand: a peak before the sun is up, another after it has gone, and a quiet middle of the day.
Three things index them. The annual generation, which comes from the MIS 3002 output estimate. The household's annual consumption from a bill based on actual meter readings, which defaults to the British average of 3,500 kWh where it is unknown. And the weekday occupancy pattern, which is 'home_all_day', 'in_half_the_day' or 'out_all_day'; where the pattern is unknown MGD 003 says to use the middle one, and that is what an omitted value resolves to.
Battery capacity is the USABLE capacity, which is smaller than the figure printed on the battery. Supplying import and export prices adds a value in pounds to the result.
Note that self-consumption is not the same as independence from the grid, and the result reports both.
Method from MGD 003. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| occupancy | No | Weekday occupancy pattern: 'home_all_day', 'in_half_the_day' or 'out_all_day'. Defaults to 'in_half_the_day', which is what MGD 003 says to use when the pattern is unknown. | |
| batteryKwh | No | Usable capacity of any battery in kWh, which is smaller than the headline capacity. Omit or use 0 for no battery. | |
| exportPricePerKwh | No | What the household is paid for a unit exported, in pounds. Optional. | |
| importPricePerKwh | No | What the household pays for a unit of grid electricity, in pounds. Optional; supplying it adds a value to the result. | |
| annualGenerationKwh | Yes | Expected annual AC output of the PV system in kWh, as produced by the MIS 3002 estimation method. Required. | |
| annualConsumptionKwh | No | The household's annual electricity consumption in kWh, from a bill based on actual meter readings. Defaults to 3500, which MGD 003 uses where the figure is unknown. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| method | Yes | |
| occupancy | Yes | |
| batteryKwh | Yes | |
| references | Yes | |
| annualValue | No | The two added together. |
| exportedKwh | Yes | |
| importedKwh | Yes | Units still bought from the grid over the year. |
| batteryGainKwh | No | Extra units kept in the house each year because of the battery. |
| occupancyLabel | Yes | |
| selfConsumedKwh | Yes | |
| annualBillSaving | No | Value of the units not bought, in pounds. Only present when an import price was given. |
| annualExportIncome | No | Value of the units exported, in pounds. Only present when an export price was given. |
| consumptionAssumed | Yes | True when the 3500 kWh default stood in for a figure the caller did not give. |
| annualGenerationKwh | Yes | |
| annualConsumptionKwh | Yes | |
| withoutBatteryPercent | Yes | What the same system would self-consume with no battery. |
| selfConsumptionPercent | Yes | Proportion of generation used in the home instead of exported. |
| gridIndependencePercent | Yes | Proportion of the household's own consumption met by the system instead of by the grid. Different from self-consumption, and usually smaller. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description adds real value: the tables are empirical monitoring data rather than a model, defaults are disclosed (3,500 kWh consumption, middle occupancy pattern), battery capacity is usable not headline, and supplying prices adds a pounds value to the result.
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 purpose is front-loaded in the first sentence, but the body runs long across four dense paragraphs, and the monitoring-data flavor about demand peaks and quiet middles is atmospheric rather than actionable. Useful content is present, but it is not tightly sized for a single calculator call.
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, the description needn't explain return values, and it still covers everything else an agent needs: data provenance, the three indexing inputs, defaulting behavior, the battery-capacity caveat, the effect of price inputs, and a professional-use disclaimer.
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 schema already documents every parameter, including defaults and the usable-capacity caveat. The description largely restates that same information (MIS 3002 generation, 3,500 kWh default, middle occupancy, price effect), adding rationale but little semantic content beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: estimate the proportion of a PV system's annual output consumed in the house versus exported. It also draws a conceptual boundary (self-consumption is not grid independence), but it never names a sibling tool such as solar_pv_output or solar_pv_system_size, so differentiation is inferred 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?
Gives clear context: these calculators follow published MCS methods and are for understanding a system and checking a quotation, plus a caveat that installed systems still need a design and site survey. It stops short of naming alternative tools or explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a completed MCS sunpath shading assessment into a shade factor, using the procedure in MGD 005.
The MCS sunpath chart is divided into 84 segments, each worth one per cent of the year's useful irradiance. An assessor stands at the middle of where the array will go, plots what blocks the horizon onto the chart, and counts the segments covered. This tool takes that count and returns 1 minus the loss, which is the SF term in the MIS 3002 output estimate.
Objects within ten metres of the array are near shading and are assessed separately, from each affected part of the array, not from its middle. They can be listed here for the record, but MGD 005 is explicit that near shading has a considerable effect and should be avoided.
This tool does not perform the assessment. It does the arithmetic on an assessment somebody made.
Method from MGD 005. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| segments | Yes | Number of segments on the MCS sunpath chart that the obstruction touches, from 0 to 84. Each segment is worth one per cent of the year's irradiance. | |
| nearObjects | No | Objects within ten metres of the middle of the array, each assessed from its own position on the array. Optional. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| method | Yes | |
| verdict | Yes | |
| segments | Yes | |
| severity | Yes | One of 'none', 'slight', 'moderate' or 'severe'. |
| references | Yes | |
| nearObjects | No | |
| shadeFactor | Yes | The multiplier to apply to an unshaded output estimate: 1 minus the loss. |
| shadingLoss | Yes | Proportion of the year's irradiance blocked, as a decimal. |
| shadingLossPercent | Yes | |
| totalModulesAffected | No |
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, yet the description adds real context: the tool is pure arithmetic on third-party input, near shading is assessed from each affected array part rather than the middle, and it is intended for understanding/checking a quotation rather than replacing a site survey. It does not, however, state whether listed near objects influence the returned SF, which is the one behavioral ambiguity left.
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?
Purpose is front-loaded correctly, but the body runs long: the walkthrough of how an assessor plots obstructions onto the chart is background that duplicates the schema's own segment explanation, and the closing MCS disclaimer paragraph is boilerplate. Both are defensible but not tightly earned, so the definition is longer than it needs to be.
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 not be described, and annotations cover the safety profile; the description fills in method provenance (MGD 005), scope limits, and the near/far shading distinction. The only material omission is whether nearObjects affects the computed shade factor.
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 above that by explaining the domain meaning of the segment count (84 segments, each one per cent of yearly useful irradiance) and by framing nearObjects as recorded-only entries with a warning that near shading should be avoided. It slightly muddies rather than clarifies whether nearObjects feed the calculation.
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: 'Convert a completed MCS sunpath shading assessment into a shade factor', and pins the output as '1 minus the loss, which is the SF term in the MIS 3002 output estimate'. An agent can distinguish this from solar_pv_output or solar_pv_system_size without opening any 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 prerequisite is made explicit ('a completed assessment', 'This tool does not perform the assessment. It does the arithmetic on an assessment somebody made'), which cleanly scopes when to call it. It stops short of naming any sibling tool as an alternative, so it is clear context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Work out the solar PV system a UK home needs: the capacity in kWp, the number of panels, the battery to go with it, and what it would do to the electricity bill.
This runs the MCS arithmetic backwards. The other solar calculators here each answer one question about a system somebody has already specified. This one starts from what a household uses and arrives at the system that covers it, which is the question a householder actually has.
The chain is short and every link is published. Annual consumption sets the generation the array has to make. The MCS irradiance dataset behind MIS 3002 says what one kWp makes on that roof, which gives a capacity. Capacity divided by panel size gives a panel count, rounded up, because panels come whole. The MGD 003 tables then say how much of that generation the household will use and how much it will export.
Only the postcode and the roof direction are required. Direction is a compass point, not an angle: 'S', 'SE', 'SW', 'E', 'W', 'NE', 'NW' or 'N'. Give the annual consumption from a bill if it is known, since the 3,500 kWh default is only the British average. Shading can be described in words instead of measured, and a roof area caps the panel count where the roof is the constraint.
No cost is assumed. Installed prices vary far too much between houses to guess at, so a payback figure appears only when a cost from a real quotation is supplied.
Use this to size a system or to sanity-check a quotation. Use 'solar_pv_output' instead when the capacity is already known and the question is only what it will generate.
Method from MIS 3002. These calculators follow the published MCS methods, for understanding a system and checking a quotation. Anything that gets installed still needs a design and a site survey from a certified installer.
| Name | Required | Description | Default |
|---|---|---|---|
| shading | No | How much shading the roof has, in words: 'none', 'light', 'moderate' or 'heavy'. Defaults to 'none'. Use 'shadeFactor' instead if a proper MGD 005 assessment has been done. | |
| postcode | Yes | UK postcode of the property, for example 'BS1 5TR'. Only the outward code matters. Required. | |
| direction | Yes | Compass point the roof faces: 'S', 'SE', 'SW', 'E', 'W', 'NE', 'NW' or 'N'. Required. | |
| occupancy | No | Weekday occupancy: 'home_all_day', 'in_half_the_day' or 'out_all_day'. Decides how much of the generation is used at home instead of exported. Defaults to 'in_half_the_day'. | |
| panelWatts | No | Nameplate rating of a single panel in watts. Defaults to 440, which is typical of a current domestic module. | |
| roofAreaM2 | No | Shade-free roof area available for panels, in square metres. Optional; when given it caps the number of panels. | |
| inclination | No | Roof pitch in degrees from horizontal. Defaults to 35, which is typical of a British pitched roof. A flat roof is 0. | |
| shadeFactor | No | A measured shade factor between 0.5 and 1 from an MGD 005 assessment. Overrides 'shading' when given. | |
| installedCost | No | The installed cost of the system in pounds, from a quotation. Optional; supplying it gives a payback period. No cost is assumed if it is left out, because prices vary too much to guess at. | |
| includeBattery | No | Whether to size a battery alongside the panels. Defaults to false. | |
| batteryModuleKwh | No | Nominal capacity of one battery module in kWh. Batteries are sold in whole modules, so the answer rounds up to one. Defaults to 5. | |
| exportPricePerKwh | No | What the household is paid for a unit exported, in pounds. Optional. | |
| annualConsumptionKwh | No | The household's electricity use in kWh a year, from a bill. Defaults to 3500, which is the British average and the figure MGD 003 falls back on, but a real bill sharpens the answer considerably. | |
| electricityPricePerKwh | No | What the household pays for a unit, in pounds. Optional; supplying it puts a value on the answer. |
| Name | Required | Description |
|---|---|---|
| zone | Yes | |
| notes | Yes | |
| method | Yes | |
| panels | Yes | |
| battery | No | |
| shading | No | The shading description used, when one was chosen in place of a measured factor. |
| direction | Yes | |
| panelWatts | Yes | |
| references | Yes | |
| capacityKwp | Yes | The installed capacity: the panel count multiplied by the panel rating. |
| exportedKwh | Yes | |
| importedKwh | Yes | Units still bought from the grid over a year. |
| inclination | Yes | |
| roofLimited | Yes | True when the roof area given, not consumption, set the size. |
| shadeFactor | Yes | |
| paybackYears | No | Installed cost divided by the annual benefit. Only present when a cost was supplied. |
| postcodeUsed | Yes | |
| annualBenefit | No | Bill saving plus export income. |
| installedCost | No | |
| newAnnualCost | No | |
| occupancyLabel | Yes | |
| selfConsumedKwh | Yes | |
| annualBillSaving | No | |
| idealCapacityKwp | Yes | The capacity that would exactly cover a year of consumption, before rounding up to whole panels. |
| roofAreaNeededM2 | Yes | |
| currentAnnualCost | No | |
| annualExportIncome | No | |
| consumptionAssumed | Yes | True when the 3500 kWh default stood in for a figure the caller did not give. |
| annualGenerationKwh | Yes | |
| annualConsumptionKwh | Yes | |
| selfConsumptionPercent | Yes | |
| specificYieldKwhPerKwp | Yes | Kk: the kWh a kWp produces in a year at this zone, pitch and orientation. |
| gridIndependencePercent | Yes | The share of the household's own use met by the system. |
| generationAsPercentOfUse | Yes | Annual generation as a percentage of annual consumption. Above 100 means the system makes more over a year than the house uses, though not at the same times. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, idempotent and non-destructive, but the description adds substantial behavior beyond that: it discloses the deterministic MCS/MIS 3002/MGD 003 computation chain, that shading can be described in words, that roof area caps panel count, and—importantly—that no cost is assumed so no payback appears unless a real quotation cost is supplied. It also flags that installation still requires a certified installer's design and survey.
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 purpose and return values are front-loaded, and the later sections cover parameters, usage and caveats in a logical order. The middle paragraph explaining the MCS arithmetic chain is somewhat verbose for an agent's selection decision, though it does earn its place by justifying the tool's determinism.
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 14-parameter tool with a rich output schema, the description supplies everything an agent needs: required vs optional inputs, default values and their rationale, cross-parameter interactions (shadeFactor overrides shading), usage boundaries, and a domain caveat. Return values are left to the output schema, which is the correct division of labor.
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 real meaning: it names postcode and direction as the only required fields, clarifies direction is a compass point rather than an angle, explains that shading can be qualitative or measured, that roof area caps panel count, and why a bill figure beats the 3,500 kWh default. That is genuine semantic value on top of the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Work out the solar PV system a UK home needs') and enumerates exactly what it returns: capacity in kWp, panel count, battery, bill impact. It then explicitly contrasts itself with the other solar calculators, which 'answer one question about a system somebody has already specified', so an agent can distinguish it from siblings without reading any 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?
It gives explicit when-to-use ('Use this to size a system or to sanity-check a quotation') and a named alternative with the selecting condition ('Use solar_pv_output instead when the capacity is already known and the question is only what it will generate'). Nothing about routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
connection_routeheat_pump_noiseheat_pump_running_costheat_pump_sizehot_water_cylinderlist_calculatorsradiator_flow_temperatureroom_heat_losssolar_pv_outputsolar_pv_self_consumptionsolar_pv_shadingsolar_pv_system_size27 engineering compliance and calculation tools for the built environment (UK, EU, UAE).
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Rooftop solar potential, RGE installer search and quote requests. France only, no API key.
Deterministic cost calculators for HVAC, roofing, plumbing, electrical, solar, water heater.
Add one secure layer between your agents and this server.
