Ampworth

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

Beyond the annotations (readOnlyHint, idempotentHint, openWorldHint=false), the description discloses important behavioral limits: it says which procedure applies but not what the operator will decide, and instructs the agent to repeat that caveat whenever reporting a result. It also discloses the underlying method (EREC G98/G99) and that all tests are in amps per phase at 230 V across the whole premises.

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 front-loaded with the outcome (which procedure applies) before the rules, and nearly every sentence carries a decision-relevant fact. Minor redundancy: the 'export limiter never brings an installation under G98' point appears in the main prose and again in the schema 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?

An output schema exists, so return values need no explanation. For a read-only rule-evaluation calculator the description supplies everything an agent needs to call it correctly: the capacity semantics, the premises-wide scope, the phase handling context, the neighbour-proximity trigger, and the mandatory caveat about operator discretion.

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 carries the basics. The description still adds real semantic value: registered capacity is the inverter's AC rating, not panel kWp; designCapacityKw matters only for inverters capped below hardware rating because G99 tests it separately; a battery counts as generation even if it only charges from panels; every exporting inverter including existing ones must be listed. It adds meaning beyond the schema for several fields.

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 precise verb and outcome: determining which ENA connection procedure (connect-and-notify vs apply-and-wait) a domestic solar/battery installation falls under. It names the governing documents (EREC G98/G99/G100) and the exact decision rules, so an agent can distinguish it cleanly from the solar_pv_* sizing and output calculators.

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 explains the domain logic thoroughly and frames the tool as a method-following calculator 'for understanding a system and checking a quotation', which implies when it applies. However, it never names a sibling tool or states when another calculator should be used instead, and gives no explicit exclusions, so usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the safety profile is covered. The description adds real behavioral value beyond them: the output is Markdown not HTML, the response carries MCS source documents and calculator ids, and question-sets return Q&A separately.

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-loads the core action in the first sentence, then layers return-shape and citation guidance. Every sentence carries information, though the final citation instruction is advisory rather than operational and slightly dilutes focus.

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

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

For a single-parameter read tool with an output schema and full safety annotations, the description covers what is needed: what it returns, in what format, and how to obtain the required slug. 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% and the parameter description already says 'from search_documents or list_documents. Required.' The description repeats the slug provenance but adds no syntax, format, or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: fetch the full text of one guide/article/question-set by slug. It distinguishes itself from siblings by noting slugs come from search_documents or list_documents, so an agent can tell retrieval-by-id apart from listing/searching.

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

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

The description makes the workflow explicit by telling the agent the slug must come from search_documents or list_documents, which effectively routes discovery through the siblings. It stops short of stating when not to use it (e.g., when only metadata is needed), so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine domain behaviour: input provenance (product fiche, energy label, MCS product database), the prohibition on using low-noise-mode figures, the sound-power vs sound-pressure trap, and the logarithmic combination of multiple units.

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 and logically ordered (purpose, formula, each variable, caveats), but a substantial share of the text restates the input-schema descriptions almost verbatim, which is space that does not earn its place given 100% schema coverage.

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. Inputs, units, the governing standard, the pass/fail threshold, multi-unit handling, and the professional-liability disclaimer are all covered, so an agent has everything needed to invoke this 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 100% and the description's parameter prose largely mirrors the schema (Lw, Q, r, Ab definitions). It still adds conceptual meaning the schema lacks: the directivity mapping (Q=2/4/8 for one/two/three surfaces), the note that more than three surfaces cannot meet MCS 020 at all, and the warning that the nearest position is not always the worst.

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 gives a precise verb and resource (calculate sound pressure level of an air source heat pump at an assessment position) plus the regulatory test applied (37 dB(A) permitted development limit, MCS 020). This clearly separates it from siblings such as heat_pump_size and heat_pump_running_cost, which cover entirely different calculations.

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

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

Usage context is explicit: 'for understanding a system and checking a quotation', with the closing caveat that installed work still needs a design and site survey. It also states the assessment position definition (habitable room window/door of a neighbouring property) and that each affected position must be checked separately. It does not, however, name or route to any alternative tool.

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 the safe-read profile (readOnlyHint, idempotentHint, non-destructive), so the description wisely spends its words on domain behavior instead: the break-even ratio that decides the answer, the default appliance efficiency, and the warning that SCOP must match the design flow temperature. This is substantive context beyond the structured fields, though it does not discuss precision or edge cases in inputs.

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 and each paragraph carries distinct information (units, the ratio, the SCOP caveat, scope exclusions). It is longer than ideal, with the flow-temperature explanation somewhat verbose, but nothing is purely filler.

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

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

With four required parameters, nine total properties, a 100% documented schema, and an output schema, the description supplies everything an agent needs: what is computed, what is excluded, the critical SCOP constraint, and the note that the break-even figure is reported explicitly. No material gap remains.

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 goes beyond it by explaining fuel-specific units (kWh/litres/kg), the meaning of the break-even comparison, and why SCOP must correspond to the actual design flow temperature rather than the badge figure.

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 states a specific comparison verb and both resources: household heating spend on current fuel versus the same heat from a heat pump. This clearly separates it from siblings like heat_pump_size or heat_pump_noise, which address different questions.

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 when this calculator applies ('running cost comparison') and explicitly excludes capital cost and grants, and it names the MCS 007 method plus the caveat that installation still needs a site survey. It does not, however, route to a specific sibling calculator for sizing or noise, leaving the alternative selection to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, not destructive), so the description exceeds the bar by disclosing the method (coefficient from degree days, peak load from MIS 3005-D Table 2), the caveat that the fabric route is not MCS-derived, and the design-flow vs headline-rating distinction. This is unusually rich context for a calculator.

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?

Reasonably front-loaded (purpose, then the IMPORTANT caveat, then the two routes), and the length is defensible for an 18-parameter calculator. It loses a point for mild repetition, notably the instruction to flag limits being restated for the metered and fabric routes separately.

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 fully for the tool's complexity by documenting method provenance, the design-temperature basis, and the recommended framing of results. Nothing an agent needs to invoke or report this 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?

With 100% schema description coverage the baseline is 3, but the prose adds genuine relational meaning beyond per-field docs: it explains that annualFuelUse and the fabric parameters are mutually exclusive routes, that quotedHeatPumpKw drives a plausibility check, and that flowTemperature governs four cost scenarios. It does not restate individual field syntax.

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

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

States a specific verb+resource (estimate heat pump size for a UK house) plus a secondary function (running-cost comparison against current fuel). It is clearly distinguishable from siblings like room_heat_loss, heat_pump_running_cost and radiator_flow_temperature, which it never overlaps.

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

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

Explicitly lays out two routes, names the metered-fuel route as preferred and the fabric route as fallback, and states the trigger for each (annualFuelUse present vs absent). It also names the shape of use (checking whether a quotation is plausible) and points to the room-by-room calculation as the alternative for actual design.

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 this a safe, idempotent, non-destructive, closed-world read, so the description's job is to add method and outcome context — and it does: it discloses the demand formula (45 l/day per N, N = max(bedrooms+1, occupants)), the reheat-time relationship (volume × ΔT / (14.3 × kW)), and the three outputs returned (BS 6700 minimum, rounded recommended size, reheat time). It also flags the coil-size caveat that a heat pump cylinder needs a larger coil than a boiler cylinder.

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 the demand rule are front-loaded, and the paragraph structure maps sensibly onto method, sizing logic, and caveats. It is longer than strictly needed for invocation — the coil-size paragraph is explanatory rather than operational — but no sentence is filler.

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

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

With an output schema present the description need not enumerate return fields, yet it still describes what the result contains. For a six-parameter engineering calculator with a formula-based method, the description supplies the standard reference, the core equation, default behaviour, and the professional disclaimer, leaving nothing an agent needs in order to call it 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 description coverage is 100%, so a baseline of 3 applies, but the description goes further by explaining the interaction between parameters: occupancy defaults to bedrooms-plus-one logic for new builds, and a larger heat pump means a smaller cylinder because reheat time falls with kW. It also contextualises storageTemp by noting the separate weekly pasteurisation cycle above 60.

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: working out daily hot water demand for a dwelling and the cylinder volume a heat pump requires, citing MIS 3005-D 3.5.2 and BS 6700/MGD 007. This is clearly distinguishable from siblings like heat_pump_size, room_heat_loss or radiator_flow_temperature, which address different calculations.

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 a clear usage frame: 'for understanding a system and checking a quotation', and warns that installed work still needs a design and site survey from a certified installer. It stops short of routing the agent between alternatives (e.g. when to use heat_pump_size instead), so it is clear context without exclusions.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuine behavioral content beyond that: it enumerates the categories of reference data returned (compass directions, postcode zones, design temperatures, etc.), telling the agent what knowledge it gains.

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 core purpose, then a dense but purposeful enumeration of the reference datasets, closing with the usage trigger. Every clause carries information, though the long middle list is heavy for a single sentence.

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 parameters, an output schema present, and rich annotations, the description need not explain return structure or safety. It covers purpose, scope, returned content categories, and the invocation condition, so an agent has everything needed to call it correctly.

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

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

The tool takes no parameters, so there is nothing to disambiguate; the baseline for a zero-parameter tool is 4. Nothing in the description misleads about inputs.

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 (lists) and resource (every calculator plus its reference data), and disambiguates what kind of calculators (whole-system sizing vs single-method) so an agent can distinguish it from the sibling calculator tools like heat_pump_size or solar_pv_system_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?

Explicitly gives the trigger condition: 'Call this when a value must be one of a fixed set and you are not sure what the set is.' This is clear context for invocation, though it does not name which sibling to prefer or state exclusions when a value is already known.

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=false, so the safety profile is fully covered without description help. The description adds that the listing is exhaustive ('every document') and that filters are optional, but says nothing about pagination, result volume, or auth needs — modest added value on top of rich 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-loads the core verb and resource, then layers filters and usage in a single tight paragraph with no filler sentences. The perspective enum list and the 'first four are plain language' clause duplicate what the schema fields already say, which is mild redundancy but does not bloat the text.

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 the description is not obliged to describe return values, and it covers what remains: scope of the listing, optional filters, domain-specific filter semantics, and when to prefer this over searching. 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 description coverage is 100%, and articles/guides-only constraints plus enum meanings are already documented per-field in the schema. The description largely restates the 'perspective' and 'level' values, adding interpretation ('match the reader') but little syntax or format detail the schema lacks. Baseline 3 is correct.

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 ('Lists') plus resource ('every document') and immediately scopes it with the available filters. The final sentence implicitly distinguishes it from search_documents by positioning it as the browse-the-shape tool rather than the lookup tool, so an agent can route correctly.

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 when-to-use guidance: 'before searching, or when a search returned nothing' — the second clause is a genuine fallback rule that names the sibling's failure mode. It also instructs how to pick filter values ('Match the perspective to the person asking'), which is actionable selection guidance rather than vague 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real domain behaviour: efficiency falls ~2-3% per degree of water temperature, star ratings scale one star per 5 degrees with six stars at 35C, and a caveat that installed systems still need a certified installer. It stops short of stating validity bounds or how out-of-range inputs are handled.

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 purpose, which is good, but it runs five paragraphs and includes economic rationale ('cheap or expensive to run') and a restatement of the 50 K/60 K point that overlaps the schema. The method and installer caveats earn their place; the economic lecture 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?

An output schema exists, so return values need not be spelled out, and the description correctly covers inputs, method provenance (MGD 007 section 4 / BS EN 442), workflow, and interpretation of the star rating. It is complete enough to invoke correctly, with only minor gaps around edge cases.

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 fully documents all five parameters and the baseline is 3. The description adds interpretive framing (heat loss in watts from a room-by-room calc, catalogue ratings normally at 50 K, restated if 60), but largely echoes what the schema already states for ratedAtDeltaT and radiatorOutputW. Marginal added meaning over the structured fields.

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: compute the flow temperature a heat pump must produce through a given radiator, plus the resulting MCS star rating. This is clearly distinguishable from siblings like room_heat_loss (which produces the heat-loss input) and heat_pump_size. An agent can identify the tool without opening the 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?

Gives strong operational context: 'Run this for every room' and explains that the whole house runs at its worst room's flow temperature. It also implies the pipeline dependency on a room-by-room heat loss figure. However, it never explicitly names a sibling tool (e.g. room_heat_loss) as the source of the input, so the routing is implied rather than stated.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description goes well beyond them: it discloses validation behaviour ('tabulated values are minimums... a lower one is refused'), the kind-dependent temperature basis, the ground-floor special case, and the default for unheatedTemp. That is real behavioural context an agent cannot get from 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?

The core definition is front-loaded in the first sentence and each paragraph serves a distinct purpose (method, room temperatures, design basis, element kinds, disclaimer). It is nonetheless long for a single tool, with the closing MCS disclaimer paragraph adding bulk more than invocation guidance.

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 domain-heavy calculation with an output schema already present, the description supplies everything an agent needs: method, required inputs, validation rules, defaults, and the common modelling error. Nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it maps roomType to concrete temperatures (22 bathroom, 21 living/dining, 18 bedrooms/halls/kitchens/toilets) and explains that 'kind' fixes which temperature difference applies. It largely restates the a/b column note and defaults already present in the schema, which keeps this short of a 5.

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 precise verb+resource+unit ('Calculate the design heat loss of a single room in watts'), names the standard it follows (BS EN 12831 / MIS 3005-D), and positions the output as the figure a heat pump is sized from, which cleanly separates it from the aggregate heat_pump_size 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?

Gives clear operational guidance ('Run this once for each heated room and add the results') and explicitly warns against the wrong approach (sizing a heat pump from floor area alone). It implies but never names heat_pump_size as the aggregation step, so there is no explicit alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, but the description adds behavior the schema and annotations cannot: results are summaries rather than full documents, matched sub-questions return inline with their answers, and coverage is limited to the United Kingdom. These are real operational facts an agent needs before calling.

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 purpose and the primary usage directive, and each paragraph carries a distinct fact (scope, follow-up tool, inline Q&A, geography). The closing two sentences about UK coverage slightly restate the opening scope, costing a little tightness.

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

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

An output schema exists, so return structure need not be spelled out, and the description still covers the essentials: what the corpus contains, what results look like at a high level, the follow-up path, and the geographic boundary. Nothing needed 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?

Schema coverage is 100%, so both the query and limit parameters are already documented in the schema, including 'plain words work best' and the 1-25 range. The description adds no syntax, format, or ranking detail beyond that, so the baseline 3 applies.

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

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

Names a specific verb and resource ('Search the guides, articles and questions') and scopes the corpus to UK home energy subjects. It also distinguishes itself from the sibling get_document by stating that searching returns summaries and get_document reads one in full.

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

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

Explicitly says to use this first before answering from memory, enumerates the question types it covers (sizing, standards, quotations, planning permission), and routes the agent to get_document as the follow-up. That is close to a complete when-to-use instruction.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the exact computation formula, the UK-only dataset limit ('no values for anywhere else'), and the disclaimer that results are for understanding/checking rather than design. It does not describe what happens on an out-of-UK postcode or other error paths.

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 method are front-loaded in the first two paragraphs, and the closing caveat earns its place. The orientation convention sentence, however, is lifted straight from the schema and is pure duplication that could be cut.

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

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

For a calculator whose output schema exists (so return values need no explanation), the description covers method, domain conventions, geographic limits and usage caveats. The one remaining gap is behavior on invalid or non-UK input, which is only implied by the 'no values for anywhere else' note.

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

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

Schema description coverage is 100% and every parameter is already documented there, including the orientation convention and the postcode/zone alternative. The description restates the orientation convention almost verbatim and adds no new syntax or format detail, so it sits at the baseline for a fully documented 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 with units: 'Estimate the annual AC electricity output of a UK solar photovoltaic system, in kWh.' It also pins the method (MIS 3002 / MCS) and the geographic scope. However it never names or contrasts against the obvious siblings solar_pv_system_size, solar_pv_shading, or solar_pv_self_consumption, so the agent must infer the boundary from the names alone.

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

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

It gives a usage context ('for understanding a system and checking a quotation') and a caveat that anything installed still needs a design and site survey from a certified installer. But it never says when to prefer this over the sibling PV calculators, nor what inputs make it inapplicable beyond the UK-only scope note.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: the provenance of the lookup tables (Loughborough half-hourly monitoring, modelled battery), the three indexing inputs, the documented defaults (3,500 kWh consumption, 'in_half_the_day' occupancy), the fact that supplying prices adds a pound value to the result, and that both self-consumption and grid independence are reported.

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 and the structure moves cleanly from what it does, to the data source, to the inputs, to caveats. It is a little long, with the monitoring-data flavor paragraph and the MCS/installer boilerplate doing less work than the parameter guidance, but nothing is confusing or misplaced.

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 described, and the description still tells the agent everything else it needs: defaults for omitted inputs, the units and meaning of battery capacity, the effect of supplying prices, and the distinction between the two reported metrics. For a six-parameter calculator this is 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?

Schema coverage is 100%, so the baseline is 3, but the prose adds genuine meaning: it explains why battery capacity must be usable (smaller than the headline figure), why generation should come from MIS 3002, and why consumption should come from a metered bill. It largely reinforces rather than extends the schema text, so it stops short of a 5.

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

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

The description opens with a specific verb and resource: estimating the proportion of a domestic PV system's annual output that is self-consumed versus exported. It even pre-empts a likely confusion by stating that self-consumption is not grid independence, which separates it from solar_pv_output (generation) and solar_pv_system_size (sizing) without needing to name 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?

Usage context is implied rather than stated: the closing lines say these calculators are 'for understanding a system and checking a quotation.' There is no explicit when-to-use versus solar_pv_output or solar_pv_shading, no stated prerequisites (e.g. run solar_pv_output first), and no exclusions. The agent must infer the routing.

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 a safe, idempotent, closed-world read-only calculation, so the bar is lower. The description adds real context beyond them: it is a pure arithmetic step with no side effects, the method source is MGD 005, and nearObject entries are informational ('listed here for the record') rather than affecting the shade factor computation.

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 and clear, but the passage runs several paragraphs and includes assessor methodology and a trailing MCS-methods/certified-installer disclaimer that does not help an agent invoke the tool. Useful content is diluted by educational and legal 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, and annotations cover the safety profile. For a two-parameter, domain-specific calculator the description supplies enough method and boundary context to call it correctly, with only minor gaps around how nearObjects influence the result.

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

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

Schema coverage is 100%, so the schema already documents both parameters thoroughly, including the segment/1%-irradiance relationship. The description largely restates that domain fact rather than adding new parameter-level detail; the '1 minus the loss' framing ties to the result but not to specific arguments. Baseline 3 is appropriate.

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

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

The first sentence states a precise verb and resource: converting a completed MCS sunpath shading assessment into a shade factor via the MGD 005 procedure. It explicitly clarifies the boundary ('This tool does not perform the assessment. It does the arithmetic on an assessment somebody made'), which cleanly separates it from the assessment and the other solar_pv calculators (output, self-consumption, 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?

Usage context is clear: it applies only once an assessment has already been completed, and near-shading objects are assessed separately 'from each affected part of the array, not from its middle.' No sibling tool is named as an explicit alternative, so it stops short of full routing guidance, but the preconditions are well conveyed.

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

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

Annotations already cover the safety profile (read-only, idempotent), yet the description adds substantial behavioral context: panels and battery modules round up because they are sold whole, no cost is assumed so payback appears only when a real quotation is supplied, defaults are the British averages, and the method provenance (MIS 3002, MGD 003, MGD 005) is disclosed. This is far beyond what 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?

Front-loaded with what the tool does and why it differs from siblings; the method paragraph and provenance are informative rather than filler. It is longer than strictly necessary ('The chain is short and every link is published' is flourish) but nothing is misleading or redundant.

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, output-schema-backed calculator this is complete: required vs optional inputs, defaults, rounding behavior, the no-cost assumption, and the installer/survey caveat are all covered, and return values are 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 meaning beyond the schema: direction is framed as a compass point rather than an angle, the 3,500 kWh default is tied to the British average/MGD 003 fallback, and installedCost is explained as the trigger for a payback figure. It stops short of adding syntax detail for every parameter, so not a 5.

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

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

States a specific verb+resource with scope: sizing a UK solar PV system (kWp capacity, panel count, battery, bill impact). It explicitly distinguishes itself from the other solar calculators as the one that works backwards from consumption rather than describing an already-specified system.

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 both use cases ('size a system or sanity-check a quotation') and names the alternative with the condition that selects it: use 'solar_pv_output' when capacity is already known. No inference required.

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