IFC models: duct networks, circuits, pressure drop. EN 12828 vessels, EN 378, Swiss refrigerants.
Scored across 11 tools
The set splits cleanly into an IFC pipeline (upload → overview → rules → networks → naming → circuit tracing) and four independent engineering calculators, and the descriptions explicitly police the boundaries (e.g. check_en378_zones vs check_refrigerant_switzerland, size_expansion_vessel vs water_content_from_vessel). The only residual overlap is among the three model-reading tools (read_ifc_overview, read_ifc_networks, trace_duct_circuits), which all 'read the model' with different outputs, and open_ifc_upload vs ifc_upload_result — though the descriptions do state an ordering.
Most names follow a verb_noun pattern (open_ifc_upload, read_ifc_overview, apply_ifc_rules, name_ifc_networks, trace_duct_circuits, check_en378_zones, check_refrigerant_switzerland), with the 'ifc_' infix acting as a predictable domain marker for the model-handling group. The two exceptions — size_expansion_vessel and water_content_from_vessel — use noun-based constructions, a minor deviation in an otherwise readable scheme.
Eleven tools sit in the sweet spot: seven cover the IFC circuit-design workflow end to end, four cover distinct normative calculations (EN 378, Swiss ORRChim, EN 12828 vessel sizing, reverse water-content deduction). No tool looks redundant or vestigial.
The IFC lifecycle is covered all the way from upload through status, model index, rule application, network reading, naming, and circuit computation, with outputs (3D link, control page, Excel workbook, Dynamo script) delivered by the existing tools. Minor gaps: no tool for plumbing/heating circuit tracing or pressure-drop retrieval outside a circuit call, and no way to clear/restart an upload session, but agents can work around these.
Turn what you read in the overview into rules the tool replays on EVERY piece of the model, including the ones you were never shown.
NOT NEEDED ON A MODEL ALREADY TREATED: when read_ifc_overview returns 'designation_existante', the units and fans are already designated - reuse them. Posting rules REPLACES that designation entirely: do it only when the user asks to start again, or when the designation plainly contradicts what they say.
THIS IS HOW THE TOOL LEARNS A MODEL. read_ifc_overview gives you one line per family of types, not one per piece. You answer with RULES on those groups, and this tool applies them to the three thousand pieces. You never give a verdict piece by piece: the result stays deterministic because a program, not you, does the matching.
THEN READ THE ANSWER BACK, AND EXPECT TO POST AGAIN. The answer gives every group with the role your rules gave it and how many pieces that is. A rule that is too wide shows up on one line — « Gaine rectangulaire cadree, 471 pieces, centrale_de_traitement_d_air » is a rule that turned every duct into an air handling unit. Narrow it and post again. Calling this tool costs nothing and may be repeated as often as you need.
WHAT NEEDS A ROLE, AND WHAT DOES NOT. Plain ducts and fittings need none: they are network by nature, and the answer marks them segment_ou_raccord so you can see at a glance whether a rule caught them by mistake. What needs a role is everything else — air handling units, fans, fire dampers, balancing dampers, silencers, louvres, diffusers — plus whatever must be kept OUT of the network, such as access zones, equipment plinths or damper motors.
THREE ROLE NAMES ARE FIXED, because circuits start from them: give air handling units, monoblocs and ventilation casings the role centrale_de_traitement_d_air, fans the role ventilateur, and SMOKE EXHAUST fans - including fans that bring compensation air for smoke exhaust - the role ventilateur_desenfumage - exactly these words. A smoke fan runs only in a fire, with the ventilation stopped: a duct it shares with an air handling unit is not a plenum shared by two installations, and the tool does not cut the networks there. Read the names, families and types: « désenfumage », « DES », « smoke », « Entrauchung », « RWA ». ONLY EQUIPMENT THAT MOVES THE AIR gets one of them: a unit is a box with a fan in it. Heating and cooling coils, heat exchangers, filters, silencers, dampers, fire dampers, VAV boxes, humidifiers are NOT units: the air runs through them, they are pieces of the network. Give them another role (coil, silencer, damper...) or none - never one of the unit roles. A coil in 'equipements' is a rule that is too wide. BUT A FAMILY WHOSE NAME SAYS IT IS A UNIT IS A UNIT - CTA, AHU, UTA, monobloc, caisson, centrale, Lüftungsgerät - even when its type describes its heat recovery: « BG_CTA_Echangeur à plaques » is an air handling unit with plate heat recovery, not a heat exchanger. A heat exchanger is a network piece only when it is a separate piece in a duct run. The answer lists, under 'equipements', the GUIDs of every piece of the model that got one of these roles: that list is what trace_duct_circuits starts from, and what the pages show as units. Every other role name is yours to choose.
A MONOBLOC BUILT FROM MODULES. Many air handling units are modelled as casings set end to end, each its own piece: filter casing, coil casing, heat exchanger or heat recovery casing, humidifier, washer, fan section, damper casing, empty casing. Give every such MODULE the role composant_de_monobloc - exactly these words - and its fan section(s) the unit role as usual. The tool then joins the modules that touch each other face to face (over 0.25 m2 of contact) into ONE unit: every duct on any module becomes one of its branches, and two fans of the same casing become one unit. Only modules of a unit get this role: a coil, a filter or a silencer fitted IN a duct is a piece of the network, and an equipment frame or plinth is not a module.
ORDER THE LIST YOURSELF, most specific first, down to the most general. The fire damper rule must come before the balancing damper rule, or « damper » takes everything. Equipment must come before terminals: « VEN_MSF_MONOBLOC_SIMPLE_FLUX_REPRISE » contains « reprise », and a return-diffuser rule placed first would claim the air handling unit.
Pieces no rule catches are simply listed, with no warning and no failure: the engineer judges on the 3D view, not on a coverage report.
NEXT: once 'equipements' lists the air handling units and fans you expect, call trace_duct_circuits with only the token. It computes nothing yet: it checks that the units are connected to the networks and returns the complete list of units and fans, to choose from - see trace_duct_circuits. 'equipements' counts every piece ('pieces') but lists at most thirty names: the count, not the list, is the model.
| Name | Required | Description | Default |
|---|---|---|---|
| rules | Yes | Your rules, as a JSON object. The only required key is roles.liste: an ORDERED list, FIRST MATCH WINS, most specific first. Each entry is {"role": "a_name", "si_un_de": [conditions]} and may also carry si_tout_de (all must match) and sauf_si (none may match). A condition names one field or one property, and one operation: {"champ": "nom_du_type", "contient": ["cta"]} {"propriete": "Mechanical.System Name", "commence_par": ["VEN_"]} Fields: classe, predefined_type, object_type, nom_brut, classe_du_type, nom_du_type, predefined_type_du_type, element_type_du_type - the same ones read_ifc_overview shows under 'identite'. Operations, from widest to narrowest: contient (anywhere, even inside a word), mot_commence_par (at the start of a word), commence_par (start of the string), finit_par (end of the string), mot_entier (a whole word), egal (the whole string). Case and accents are ignored, and _ - . / are read as spaces. You may also pass dimensions, noms_de_systeme and debits_et_pertes; they are kept as given. | |
| token | Yes | The model token, from ifc_upload_result or from the link the user pasted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that posting REPLACES prior designation, that matching is deterministic and program-driven rather than piece-by-piece, that unmatched pieces are silently listed without warning or failure, and that 'equipements' counts every piece but names at most thirty. These are substantive behavioral details an agent could not infer from annotations alone.
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 section headings help navigation, but the description is extremely long and repetitive in places, with conversational asides and all-caps blocks. Much of the guidance is relevant, but it could be tightened considerably without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex, output-less tool, the description explains what the answer will contain (groups with roles and piece counts, the 'equipements' list), how to react to it, what happens to unmatched pieces, and how to proceed to trace_duct_circuits. No major operational 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 schema already documents the rule object, fields, operations, and ordering. The description adds essential semantics not present there: the three fixed role names (centrale_de_traitement_d_air, ventilateur, ventilateur_desenfumage), the composant_de_monobloc module role, module-joining behavior, and ordering heuristics such as fire damper before balancing damper.
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 precise operation: turning overview-derived rules into a deterministic classification applied to every model element. It also explicitly contrasts itself with read_ifc_overview (what you read) and trace_duct_circuits (the next step), so an agent can distinguish it from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use and when-not-to-use guidance: do not post when 'designation_existante' is present unless the user asks to restart or the designation plainly contradicts them; expect to read the answer and repost to narrow over-wide rules. The alternative sibling for the next step is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DETERMINISTIC: the same inputs always give the same result — from any AI, on any day. Figures come from the standard's tables and formulas, never from a language model's estimate. Every step is auditable.
EN 378 applied to BUILDING projects, volume by volume.
An installation does not occupy one room but several: the machine, the rooms crossed by refrigerant lines, the rooms served by indoor units. Each volume is classified on its own — access category (a/b/c) and location class (I–IV) — and each classification calls for its own measures. The tool answers per volume, never as a single verdict.
It returns, for every volume: its classification and why, the charge limit from Tables C.1 and C.2 of EN 378-1 (with the C.2 formula computed when the table calls for it), whether the charge exceeds it, the EN 378-3 measures that follow, the applicable texts (EN 378-1 to -4, EN IEC 60079-10-1, SUVA 66139 and 2153) and the ventilation flow rates.
FOUR CONFIGURATIONS COVER ALMOST EVERY BUILDING PROJECT. Bring the user's case back to one of them wherever possible: machine_en_local_technique chiller or heat pump, all refrigerant inside the machine, standing in a plant room -> c III enceinte_accessible_fermee all refrigerant inside a walk-in ventilated enclosure that stays closed even for maintenance -> the enclosure is c III, the room around it carries no requirement enceintes_inaccessibles one or more units, each in a manufacturer's non-accessible ventilated enclosure -> TWO analyses: the enclosure in operation (class IV, the manufacturer sizes and justifies it, ask him for the enclosure ventilation), and the plant room with the enclosure OPEN for maintenance, which comes back to c III split_traversant split or VRF outdoors, refrigerant lines crossing occupied rooms -> each room on its own; offices and their circulations are b I, and formula C.2 gives the maximum charge for the floor area, or the minimum floor area for the charge
THIS TOOL ANSWERS SAFETY IN THE ROOM. It says NOTHING about whether the
refrigerant may still be placed on the market or refilled: in Switzerland that
is check_refrigerant_switzerland. A question that mixes both - « may I use
R-32 for 3 kg in a server room, and until when can I refill it » - needs BOTH
tools: call this one for the room, and check_refrigerant_switzerland for the
dates. Do not answer half the question.
NEVER guess. The refrigerant, the configuration and the charge are always
needed; a split also needs the floor area and how the indoor unit is mounted
(floor, wall, window, ceiling), since C.2 depends on it. Without them the
result is provisional and carries questions_to_ask: ask them, one or two
at a time, then call again.
Answer from answer_outline, volume by volume. In building projects,
detection is preferred over treating a plant room as an ATEX zone. C.3 is
never used. Say that the practical limit alone proves nothing: the charge
limit of Tables C.1 and C.2 is what counts.
SCOPE: building services. Cold rooms, food refrigeration and industrial process refrigeration are a different trade.
| Name | Required | Description | Default |
|---|---|---|---|
| pose | No | How the indoor unit is mounted: on the floor, wall, window or ceiling. Formula C.2 depends on it. | |
| language | No | The user's language. Texts are in French: translate them. | fr |
| charge_kg | No | Refrigerant charge of the largest circuit, in kg. | |
| acces_local | No | Access category of the plant room. Omit: 'c', authorised persons only. | |
| refrigerant | Yes | Refrigerant as the user wrote it: 'R-32', 'R410A', 'R290', 'R717', 'propane'… | |
| configuration | No | How the installation is laid out. Omit if unknown: the tool returns the question to ask. | |
| volume_local_m3 | No | Volume of the plant room, in m³. | |
| volume_enceinte_m3 | No | Volume of the ventilated enclosure, in m³. | |
| acces_locaux_desservis | No | Access category of the rooms crossed or served: 'b' for offices, laboratories, workplaces; 'a' for hotels, schools, shops, hospitals, homes. | |
| volume_local_desservi_m3 | No | Volume of the smallest room crossed or served by an indoor unit, in m³. | |
| surface_local_desservi_m2 | No | Floor area of that room, in m². Formula C.2 needs it; without it the tool returns the minimum area required instead. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/non-openWorld, and the description goes well beyond them: determinism guarantee, the 'provisional' status with questions_to_ask when inputs are missing, the auditability of each step, and the directive that C.3 is never used and detection is preferred over ATEX treatment.
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 determinism claim and organized into scannable blocks (configurations, tool boundary, never-guess, scope). It is long, and the opening 'from any AI, on any day' line leans promotional, but nearly every sentence carries operative content.
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 complex 11-parameter domain tool, the description covers purpose, routing, required inputs, degraded-mode behavior, and scope exclusions; with an output schema present it need not detail return shapes, and it still names the key returned fields.
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 baseline is 3, but the description adds real meaning: it states which inputs are always needed (refrigerant, configuration, charge), why pose matters (C.2 depends on mounting), and that omitting configuration returns the question to ask rather than an 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+resource ('EN 378 applied to BUILDING projects, volume by volume') and makes the per-volume, non-single-verdict behavior explicit. It clearly differentiates from sibling check_refrigerant_switzerland by scoping itself to in-room safety, not market/refill legality.
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 via four named configurations with mapping guidance, states when BOTH tools are needed for a mixed question, and excludes out-of-scope trades (cold rooms, industrial process refrigeration). It even instructs the agent on the follow-up loop when inputs are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DETERMINISTIC: the same inputs always give the same result — from any AI, on any day. Figures come from the regulation's annexes and thresholds, never from a language model's estimate. Every step is auditable.
Swiss refrigerant regulation check (ORRChim / ChemRRV annex 2.10, OFEV synthesis of May 2026, rules adopted 29.10.2025) plus refrigerant data from EN 378-1 Annex E: GWP (AR4, the ORRChim basis), ODP, LFL, safety class, practical limit.
Returns, for a given refrigerant and installation: the date from which machines using it can no longer be placed on the Swiss market (import from 01.01.2027, sale to third parties from 01.07.2027), the date from which filling with virgin refrigerant is banned, the period when only reclaimed refrigerant may be used, and the date from which all filling is banned.
SCOPE: heating, air conditioning, building cooling and process cooling, data centres included. NOT food refrigeration, cold rooms or deep freezing: those are a different trade, and the tool declines them instead of answering.
Use it whenever the user asks about a refrigerant in Switzerland — its GWP / PRG, flammability, whether a chiller, heat pump, split, VRF or cold room using it may still be sold or refilled — in any language: fluide frigorigène, Kältemittel, refrigerante, refrigerant, R-32, R-410A, R-290, CO2, NH3...
The answer depends on the installation. The regulation distinguishes:
use (building cooling, food refrigeration medium / low temperature / combined /
deep freezing, process cooling, heat pump mainly for heating, ice rink), cooling
capacity Q0K or heating capacity Q0H, self-contained (factory-built packaged
unit) or not, split, direct expansion (incl. VRF), secondary coolant loop
(chilled water / brine), air-cooled condenser and refrigerant charge.
THIS TOOL ANSWERS ONE QUESTION ONLY: may the refrigerant still be sold and
refilled in Switzerland, and until when. It says NOTHING about safety in the
room - charge limits, machine room, detection, ventilation, ATEX. That is
check_en378_zones. A question that mixes both - « may I use R-32 for 3 kg in
a server room, and until when can I refill it » - needs BOTH tools: call this
one for the dates, and check_en378_zones for the room. Do not answer half the
question.
NEVER guess these. Call the tool with what the user gave: it returns
provisional: true, the possible scenarios, and questions_to_ask in the
order that matters most. Ask them (one or two at a time), then call again.
Natural refrigerants need no questions. Build your answer on answer_outline;
quote exceptions as possible, never as granted.
| Name | Required | Description | Default |
|---|---|---|---|
| split | No | True for a split system (indoor/outdoor units linked by refrigerant lines laid on site). Omit if unknown. | |
| language | No | The user's language, for labels. French or English text; translate for de/it/es. | en |
| application | No | Use of the installation: 'climatisation_batiment' (building cooling, incl. reversible heat pump used mainly for cooling), 'froid_alimentaire_positif' (food/perishables, use temp ≥ 0 °C), 'froid_alimentaire_negatif' (≥ −25 °C), 'froid_alimentaire_combine' (multiplex medium + low temp with common discharge), 'surgelation' (< −25 °C), 'froid_process' (industrial process cooling), 'pac_chauffage' (heat pump mainly for heating), 'patinoire_permanente', 'patinoire_temporaire'. Omit if unknown. | |
| refrigerant | Yes | Refrigerant designation as the user wrote it: 'R-32', 'R410A', 'R1234ze', 'CO2', 'propane'… | |
| heat_recovery | No | True if rejected heat is recovered. | |
| self_contained | No | True if 'autonome': factory-built circuits in a frame/casing and no gas-carrying part connected on site (packaged chiller, monobloc heat pump, rooftop). Omit if unknown. | |
| gwp_if_unlisted | No | ONLY if a previous call said the refrigerant is not in the database: its GWP (AR4) from the manufacturer's datasheet, given by the user. | |
| odp_if_unlisted | No | ONLY with gwp_if_unlisted: its ODP (0 for HFC/HFO). | |
| direct_expansion | No | True if the refrigerant evaporates directly in the room units / evaporators (DX, incl. VRF); False if it cools a water or brine loop. Omit if unknown. | |
| evaporator_count | No | Number of evaporators. | |
| secondary_circuit | No | True if cold is distributed through a secondary coolant loop (chilled water, glycol, brine). Omit if unknown. | |
| family_if_unlisted | No | ONLY with gwp_if_unlisted: 'naturel' (natural), 'stable' (contains any HFC/PFC — e.g. R-454B, R-454C, R-455A), 'hfo' (only HFO and/or natural components). | |
| cooling_capacity_kw | No | Peak useful cooling capacity Q0K, kW. Omit if unknown. | |
| heating_capacity_kw | No | Peak useful heating capacity Q0H, kW (heat pumps). Omit if unknown. | |
| air_cooled_condenser | No | True if heat is rejected through an air-cooled condenser (heat pump: its air heat exchanger). Omit if unknown. | |
| refrigerant_charge_kg | No | Total refrigerant charge, kg. Omit if unknown. | |
| refrigerant_circuit_count | No | Number of refrigerant circuits. | |
| simultaneous_heating_cooling | No | True for simultaneous heating and cooling with at least 2 air heat exchangers. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive, but the description adds behavior annotations do not carry: deterministic non-LLM estimates, auditable steps, provisional output with scenarios and questions_to_ask, and a refusal policy for out-of-scope trades. It also discloses the two-stage ask-then-recall interaction pattern.
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 useful routing info, but the opening DETERMINISTIC paragraph is promotional framing, and the SCOPE / ONE QUESTION ONLY / NEVER guess sections are long and partially restate the same point. The content earns its place, yet the same information could be delivered in noticeably fewer lines.
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 18 parameters, an output schema already present, and a sibling tool handling the complementary room-safety question, the description supplies everything else the agent needs: scope boundaries, the provisional/follow-up loop, the tool's limitations, and refusal behavior.
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 baseline is 3, but the description adds meaning the schema cannot: missing optional parameters yield provisional:true plus scenarios and questions_to_ask, and natural refrigerants require no follow-up questions. It does not add per-parameter syntax 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 — a Swiss refrigerant regulation check under ORRChim/ChemRRV annex 2.10 — and enumerates exactly what it returns (market-placement ban dates, virgin-refill ban, reclaimed-only window, total filling ban). It explicitly distinguishes itself from check_en378_zones by saying it answers 'one question only' and 'says NOTHING about safety in the room.'
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 trigger conditions ('Use it whenever the user asks about a refrigerant in Switzerland'), in-scope applications (heating, AC, building/process cooling, data centres), explicit exclusions (food refrigeration, cold rooms, deep freezing — declined), and a worked multi-tool example showing when to pair with check_en378_zones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where the upload stands. When state is depose, token is the
token to pass to read_ifc_networks.
| Name | Required | Description | Default |
|---|---|---|---|
| upload_token | Yes | The upload_token returned by open_ifc_upload. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds that a state field exists and that the token feeds read_ifc_networks, but it omits what happens when the state is not depose and what the full return shape looks like.
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?
Two short sentences, front-loaded with the status concept. The second sentence is somewhat opaque due to undefined state and token field references, but there is no wasted 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?
With no output schema, the description carries the burden of explaining return values, yet it only names state and token without enumerating possible states or the full response. It is minimally adequate for a low-complexity, one-parameter status tool.
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 the single upload_token parameter is fully documented in the schema. The description adds a downstream relationship to read_ifc_networks but no syntax or format detail 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 description implies a status check for an upload but never states an explicit verb like 'retrieve' or 'check'. It names read_ifc_networks as a downstream consumer, which gives some sibling context, but the core purpose remains only loosely specified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-call guidance relative to open_ifc_upload or other siblings. The conditional routing to read_ifc_networks when state is depose is useful, but it only covers one branch of usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply the names you propose, and get back the updated report.
THE NAMES ARE YOURS, THE NETWORKS ARE NOT. You are naming what the tool measured; you are not changing what it measured. Nothing you send here alters a network, a part, or a correction.
WHAT COMES BACK. The updated report, a 3D link where the user sees your names in colour, and a link to the corrective Dynamo script that writes the systems back into Revit.
ALWAYS GIVE THE USER THE 3D LINK, and say plainly which names are yours. Networks are deterministic; names are a proposal. A user who cannot tell the two apart cannot check your work.
AFTER THE USER HAS BEEN IN THE 3D VIEW, call read_ifc_networks again with the same token before saying anything about the model. They may have renamed what you proposed, assigned parts by hand, or refused a correction — and only a fresh read shows it.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | One name per network, keyed by its 'rang' as a string, for instance: {'3': 'SUPPLY L2', '7': 'EXTRACT KITCHEN'}. Only include the ones you are naming; the others are left untouched. | |
| token | Yes | The same token used with read_ifc_networks. | |
| reasoning | No | One short line per name, saying what it is based on — the neighbouring unit, the project's naming scheme, an existing system. Shown to the user, who decides. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (not read-only, idempotent, non-destructive, open-world), and the description adds meaningful context beyond them: what comes back (updated report, 3D link, corrective Dynamo script) and the crucial constraint that sending names does not alter networks, parts, or corrections. It stops short of describing error behavior or how partial/omitted names are validated, so not a 5.
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 action and the return value, then workflow instructions. Slightly repetitive: 'you are naming what the tool measured; you are not changing what it measured' restates the later 'Nothing you send here alters a network, a part, or a correction.'
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?
No output schema exists, and the description fully covers what is returned (updated report, 3D link, Dynamo script) plus the required follow-up read. Nothing an agent needs to call 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?
Schema description coverage is 100% and both params have clear schema descriptions, so the schema does the heavy lifting. The description reinforces that names are proposals rather than mutations but adds no syntax or format detail 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 ('Apply the names you propose, and get back the updated report') and immediately frames the tool against its read counterpart. An agent can tell this is the naming/write step of an IFC workflow 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?
Explicit workflow guidance: give the user the 3D link, disclose which names are proposals, and after the user has been in the 3D view call read_ifc_networks again with the same token. It names the alternative tool and the condition that selects it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show an upload box in the conversation where the user can drop an IFC file (.ifc) of a building services model (HVAC, plumbing, heating). The file goes straight from the user's browser to thenewengineer.com - you never see it.
CALL THIS when the user wants to analyse an IFC model and has not yet given you a link from thenewengineer.com. Then tell the user to drop the file in the box.
When the upload is done, the box posts a message with a token. Use that token with read_ifc_networks. If no message arrives and the user says the upload is done, call ifc_upload_result with the upload_token returned here.
Prototype: files up to the anonymous size limit of the site.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare it is a non-read, open-world, non-idempotent operation, and the description adds the mechanism: the file travels directly from the user's browser to thenewengineer.com and the agent never sees it, plus the token-return flow and a prototype size limit. That is meaningful behavioral context beyond 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?
Front-loaded with what the tool does, then the trigger condition, then the follow-up sequence. Paragraphs are short and each one carries distinct, non-redundant information; nothing 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 no input schema fields and no output schema, the description compensates by explaining the token handoff and the fallback path, which is exactly what an agent needs to complete the upload workflow. No gaps remain for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4. The description still explains the indirect data flow it produces (an upload_token returned for use with read_ifc_networks / ifc_upload_result), which is the closest thing to parameter semantics this call has.
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 action and resource: it opens an in-conversation upload box for IFC building-services models (.ifc). It explicitly scopes the file types (HVAC, plumbing, heating) and clearly differs from sibling tools like read_ifc_networks and ifc_upload_result, which it names.
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 activation conditions: 'CALL THIS when the user wants to analyse an IFC model and has not yet given you a link.' It then sequences the follow-up (read_ifc_networks with the token) and the fallback (ifc_upload_result with upload_token) when no message arrives, so both when and when-not are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DETERMINISTIC: networks come from geometry, not from a guess. The same model always gives the same networks, from any AI, on any day.
Read the networks of an IFC model already uploaded by the user.
WHAT A NETWORK IS. A set of parts that touch each other, cut at equipment: a pump, an air handling unit, a chiller separates two systems, so the tool does not run through them. This is measured on the geometry — you cannot and need not check it.
WHAT YOU GET, PER NETWORK state 'homogeneous' — a system exists, some parts were mis-named by the modeller; the tool will correct them. 'undetermined' — no system can be read. THIS is where you are useful. 'assigned' — the user or you already named it. system the dominant name, when there is one part_dominante the share of named parts carrying it equipements_voisins the NAMES of the machines this network is connected to. An undetermined network starting from 'AHU-Supply-L2' names itself — but only you can see it. systemes_existants every system name already in the model
WHAT TO DO NEXT. Propose a name for each undetermined network, using the neighbouring equipment, the existing system names, and anything the user told you about the project's naming scheme. Ask the user for their list of planned systems if you do not have it. Then call name_ifc_networks.
WHAT NOT TO DO. Do not rename a network the report calls 'homogeneous' unless its name plainly contradicts the equipment it is connected to — and then say why. Do not invent a network: you cannot see the geometry, and the tool already did that work.
CALL THIS AGAIN WHENEVER THE STATE MAY HAVE MOVED. The token stays valid for 48 hours and is a key, not a snapshot: every call recomputes and returns the model AS IT IS NOW. The user works in the browser between your messages — renaming networks, assigning parts by hand, accepting or refusing corrections. So the moment they say they have done something, or you are about to state a figure, call this tool again.
NEVER ANSWER FROM MEMORY about networks, counts or states. What you read earlier is already out of date the moment the user touches the 3D view, and a stale figure stated confidently is worse than no figure at all.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The token from the link the user pasted. It looks like the last part of thenewengineer.com/ia/XXXX. The user gets it on the model page, button 'share with my AI'. Valid 48 hours, one model. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety/idempotency profile, and the description adds substantial context beyond them: the 48-hour token validity, the fact that every call recomputes the model as it is now rather than returning a snapshot, and the exact per-network return fields. It even warns against stating stale figures, which is behaviorally important and not derivable from annotations or schema.
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 determinism claim and the core purpose, then structured into WHAT A NETWORK IS / WHAT YOU GET / WHAT TO DO NEXT / WHAT NOT TO DO. The caps-emphasis and the repeated 'never answer from memory' warning cost some tightness, but nearly every sentence carries usable 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?
There is no output schema, so the description carries the full burden of describing the return payload and does so field by field, including the meaning of each state value. Combined with the usage and caution guidance, nothing an agent needs to call and interpret this tool 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 the single token parameter is documented thoroughly in the schema (format, where the user gets it, 48h validity, one model). The description adds nothing about the token, so the baseline 3 for high coverage 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?
States a specific verb and resource ('Read the networks of an IFC model already uploaded by the user') and immediately defines what a network is, including the equipment-cut rule. It also names the follow-up sibling name_ifc_networks, so an agent can place it in the workflow without opening another 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 explicit when-to-use ('CALL THIS AGAIN WHENEVER THE STATE MAY HAVE MOVED'), what to do next (propose names, ask for the planned-systems list, call name_ifc_networks), and explicit when-not-to ('Do not rename a network the report calls homogeneous'). The routing decision is fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL THIS FIRST, as soon as the user gives you a token - a link thenewengineer.com/ia/XXXX pasted in the conversation - BEFORE you answer anything, even when the user only says they will choose or do something themselves. It answers within seconds, while the network graph is still being built - use that time to think.
THE USER WANTS TO CHOOSE THE UNITS THEMSELVES (« let me select », « je vais choisir les centrales »): the place to do it is the control page. Go on through the steps below until trace_duct_circuits (token only) returns 'lien_centrales', and GIVE THEM THAT LINK. Never tell them to select « in the interface » without the link: there is no other place to select.
A MODEL ALREADY TREATED: if the answer carries 'designation_existante', an earlier session already designated the units and fans of this model. Reuse it: skip step 2, go straight to trace_duct_circuits, and show the user the designation you reused. Post new rules only if the user asks to start again.
THE CIRCUITS OF A MODEL IN FOUR CALLS:
read_ifc_overview - this call: the types of the model.
apply_ifc_rules - your rules. Give air handling units, monoblocs and ventilation casings the role centrale_de_traitement_d_air, fans the role ventilateur, and smoke exhaust fans (and smoke compensation fans) the role ventilateur_desenfumage, exactly these words - and ONLY to equipment that holds a fan. Coils, heat exchangers, filters, silencers, dampers, VAV boxes are pieces of the network, not units - BUT a family NAMED as a unit (CTA, AHU, UTA, monobloc, caisson, centrale) is one, even when its type names its heat recovery: « BG_CTA_Echangeur à plaques » is an air handling unit. Its answer lists under 'equipements' every unit and fan of the model.
trace_duct_circuits with ONLY the token - it computes nothing, walks the networks from every unit and fan, and either returns the COMPLETE list of units and fans with the control page, or says the units could not be connected to the model's networks.
trace_duct_circuits again with the units the user wants, or all_networks=true for all of them (offered up to 50 air networks only). The answer of this call repeats these steps under 'marche_a_suivre'.
YOU SEE A SAMPLE, THE TOOL SEES EVERYTHING. This overview shows one example per type, not every piece: you cannot count the units, the fans or the networks of the model from it, and you must not believe you have seen them all. The tool applies your rules to every piece and walks every network. So never pick the networks to compute from this overview: trace_duct_circuits gives you the complete list of units and fans first, and you choose from THAT list.
WHAT YOU GET. Not 3 000 parts: an INDEX of the model, one line per FAMILY of types (the sizes of one family share its line) - dampers, terminals, equipment, proxies -, each with its IFC class, its number of pieces, an example GUID and the identity fields of its largest type ('identite': object_type, nom_du_type...), which is what rules are written on. Plain ducts and fittings need no role: they are listed in one line each under 'reseau_ordinaire', and 'cotes_exemples' shows the numeric properties of the main duct families - where height, width and diameter are.
THE DETAIL, ON DEMAND. When a family's name does not tell you what it is, call this tool again with families=[its 'famille' names] (up to 12 per call): you get every property of an example piece and every type of the family. property_catalogue=true lists every property of the model once. These follow-up calls bill nothing.
WHAT TO DO WITH IT. Write RULES, not verdicts. For roles: which words, in which field, identify a fire damper, a silencer, a balancing damper, an air terminal, an air handling unit, a fan, a pump - and which groups are NOT network at all (access zones, plinths, placeholders, damper motors). For sizes: which 'PropertySet.Property' holds height, width, diameter, length. A rule applies to every part, including those you were not shown, and to the user's next models.
TRAPS the field 'a_savoir' warns about: values are in the FILE's unit (see metres_par_unite), not millimetres; insulation sizes and hydraulic diameters look like dimensions and are not.
The field 'etat_du_graphe' says whether the networks are ready yet: 'pret' means read_ifc_networks will answer now.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The token from the link the user pasted — the last part of thenewengineer.com/ia/XXXX. Valid 48 hours. | |
| families | No | Leave EMPTY on the first call. Then, to read EVERY property of some families, their 'famille' names from the first answer - at most 12 per call. Only the detail asked for comes back. | |
| property_catalogue | No | True lists every property of the model once, by property set, with an example value - to find which 'PropertySet.Property' holds a size or a flow. Only the catalogue comes back. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, it discloses that the call answers within seconds while the network graph is still building, that follow-up calls bill nothing, that the index is a per-family sample rather than an exhaustive enumeration, and that etat_du_graphe signals when read_ifc_networks will succeed. It also names a trap the agent cannot infer: values are in the file's unit, and insulation sizes / hydraulic diameters masquerade as dimensions.
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?
Roughly 600 words of ALL-CAPS imperatives, much of it a multi-step playbook (rules for assigning roles to CTA, fans, dampers, VAV boxes) that does not describe this tool at all. Key facts are repeated, e.g. 'trace_duct_circuits gives you the complete list of units and fans first' appears twice, and the essential 'what you get' only lands midway through.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden and does so: it describes the returned index structure, the detail-on-demand path, the readiness flag, and what the agent is expected to produce from it (rules, not verdicts). For a three-parameter read tool in a multi-step pipeline, nothing an agent needs 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 description coverage is 100%, so the schema already documents token, families (max 12) and property_catalogue, and the description largely restates those constraints. It adds some genuine workflow meaning – leave families empty on the first call, and that these follow-ups are free – but not new semantics for the required token itself, 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?
The 'WHAT YOU GET' section states precisely what comes back: an index of the model, one line per family of types, each with IFC class, piece count, example GUID and identity fields. It is clearly differentiated from siblings (apply_ifc_rules, trace_duct_circuits, read_ifc_networks) and warns that it returns a sample, not the whole model. The only deduction is that the actual purpose statement is buried behind several paragraphs of imperative workflow text ('CALL THIS FIRST', 'THE USER WANTS TO CHOOSE...').
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 rules across the whole lifecycle: call first upon receiving a token, call again with families=[...] only when a family name is ambiguous, use property_catalogue=true to locate a size/flow property, and skip straight to trace_duct_circuits when designation_existante is present. It also names the alternatives and the exact condition that selects them, including what not to do (never pick networks from this overview).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DETERMINISTIC: the same inputs always give the same result — from any AI, on any day. Figures come from the standard's tables and formulas, never from a language model's estimate. Every step is auditable.
Size the expansion vessel and pressurisation of a closed heating or chilled-water circuit to EN 12828: static height, minimum pressure p0, fill pressure pa, final pressure pe, expansion volume, water reserve, nominal vessel volume with the standard vessel to buy, safety valve setting together with the minimum it must not fall below, pressure class of the lowest equipment, intermediate vessel when needed.
Heights become pressures through the real density of the fluid, at the
temperature that matters for each: the coldest for p0, the design
temperature for the valve and the lowest point. Water and glycols
therefore give different figures for the same height.
Use it whenever the user asks to size or check an expansion vessel,
pressurisation unit, pre-charge pressure or safety valve — in any
language: vase d'expansion, maintien de pression, Ausdehnungsgefäss,
Druckhaltung, vaso di espansione, vaso de expansión.
Needs the installation water volume and THREE heights, all measured
from the point where the expansion vessel connects to the network:
- the highest point of the installation, above it;
- the lowest point, usually below it (negative) or level with it;
- the safety valve, which always sits on the heat generator or
chiller. If the user does not know it, it is assumed 1 m above
the vessel connection, and the result says so.
Ask the user for the volume and the three heights before calling.
NEVER invent a height: if the lowest point or the valve height is
unknown, omit it. The result is then marked provisional and lists
the questions to ask. Build your answer on `answer_outline`: it
carries the assumptions, the questions and the link to the website,
which measures all of these on the user's IFC model.
| Name | Required | Description | Default |
|---|---|---|---|
| fluid | No | Heat-transfer fluid: 'eau' (Water), 'meg' (MEG), 'mpg' (MPG), 'tyfocor' (TYFOCOR L (MPG)). Omit: plain water. | |
| language | No | The user's language, for labels and alerts. | en |
| glycol_pct | No | Glycol concentration in %, ignored for water. Defaults to 30 %. | |
| installation | No | 'chauffage' for heating, 'refroidissement' for cooling / chilled water. Omit: heating. | |
| pressurisation | No | Type of pressurisation: 'statique' (Pressure-maintained by gas cushion (Statico)), 'compresseur' (Compressor-driven (Compresso)), 'pompe' (Pump-driven (Transfero)). Omit: gas-cushion vessel. | |
| min_temperature_c | No | LOWEST temperature the fluid can reach, °C — including a breakdown, not just normal running. Omit and the filling temperature is used; in a glycol mix the calculation already goes down to the frost protection point. | |
| flow_temperature_c | No | Flow temperature, °C. Omit: 80 in heating, 6 in cooling. | |
| design_temperature_c | No | Hottest the fluid ever gets, standstill included. Omit: the warmer of flow and return in heating, 40 °C in cooling. | |
| return_temperature_c | No | Return temperature, °C. Omit: 60 in heating, 12 in cooling. | |
| filling_temperature_c | No | Temperature at which the circuit is filled, °C. Omit: 10. | |
| installation_volume_l | Yes | Total water content of the closed circuit, in litres: pipes, emitters, generator, buffer tank. THIS IS THE WATER, NOT THE VESSEL. If you know the vessel and want the water content, this is the wrong tool: call water_content_from_vessel. | |
| lowest_point_from_unit_m | No | Height of the REAL lowest point of the installation - the lowest drain - relative to the point where the expansion vessel connects to the network, in metres. NEGATIVE when below it, 0 when the vessel connects at the lowest point. Taken as given: no margin is added. Ask the user. NEVER invent it: if the user has not given it, omit it - the result is then marked provisional and returns the question to ask. | |
| safety_valve_from_unit_m | No | Height of the safety valve relative to the point where the expansion vessel connects to the network, in metres. The safety valve always sits on the heat generator (boiler, heat pump) or chiller - tell the user so, it helps them find it. Ask for it; if they cannot say, omit it: it is then assumed 1 m above the vessel connection, and the result says so. | |
| safety_valve_setting_bar | No | Safety valve setting in bar, one of the standard settings. Omit to take the smallest standard setting that works here. A setting below the minimum the installation needs is raised, and the result says so. | |
| highest_point_above_unit_m | No | Height of the REAL highest point of the installation - the top air vent - above the point where the expansion vessel connects to the network, in metres. Taken as given: no margin is added. NEEDED FOR A STATIC VESSEL ONLY: a compressor or pump unit holds the pressure itself, and heights play no part in its sizing — do not ask for them. | |
| minimum_required_pressure_bar | No | Pressure the installation requires at the pressurisation unit whatever the height - against cavitation at a pump suction, for instance. p0 never falls below it. Omit: zero. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantially beyond them: deterministic provenance ('figures come from the standard's tables and formulas, never from a language model's estimate'), the provisional-result behavior when heights are omitted, the documented assumption that an unknown valve height defaults to 1 m above the connection, and the note that no margin is added to measured heights.
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?
Information-dense and reasonably front-loaded, but the ALL-CAPS 'DETERMINISTIC' preamble occupies the most valuable opening position before the core purpose, and the 'never invent a height / omit it' instruction is repeated later in the body and again in the schema descriptions. Slight redundancy, but nearly every sentence carries engineering-relevant content for a 16-parameter 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?
For a complex, 16-parameter tool this is complete: an output schema exists so return values need not be re-explained, yet the description still points the agent at `answer_outline` for assumptions, open questions and the reference link, and it explicitly marks when results are provisional. Nothing an agent needs to call or to report back 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 the schema itself already carries the tri-height explanation, sign conventions, defaults and 'NEVER invent it' warnings. The description restates much of that (three heights measured from the vessel connection, static-only caveat for the highest point, glycol/water density effects) rather than adding new semantic detail, so this lands at the high-coverage baseline.
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 (size expansion vessel and pressurisation of a closed heating/chilled-water circuit to EN 12828) and enumerates the concrete outputs: static height, p0, pa, pe, expansion volume, nominal vessel volume, safety valve setting, pressure class. A sibling such as water_content_from_vessel is explicitly ruled out ('if you know the vessel and want the water content, this is the wrong tool'), so the agent can separate the two without opening a 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?
States the trigger conditions ('whenever the user asks to size or check an expansion vessel, pressurisation unit, pre-charge pressure or safety valve — in any language') with multilingual synonyms, gives the mandatory precondition ('Ask the user for the volume and the three heights before calling'), and supplies exclusions ('NEVER invent a height... if unknown, omit it'). When to use, what to gather first, and what not to fabricate are all explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
THE CIRCUITS THE FANS OF A MODEL ARE SIZED ON, found without anyone clicking and computed on the pressure-drop page, where the user confirms types and flows and reads the pressure drops.
THE USER WANTS TO PICK THE UNITS THEMSELVES: call this tool with ONLY the token right away, and give them 'lien_centrales' - the control page, where a click turns a unit red and 'Send to my AI' sends you their choice. Without that link they have nowhere to select.
ONLY UNITS AND FANS ARE EXCHANGED. The tool never sends you system names: it sends the air handling units and fans your rules found, each with what the network walk finds connected to it - geometry, not names. A unit is equipment with a FAN - air handling unit, monobloc, ventilation casing, fan. Coils, heat exchangers, filters, silencers, dampers are network pieces: if one shows up in the list (often as 'dans_le_reseau_de' another unit), your rules are too wide - fix them with apply_ifc_rules before choosing. But a family NAMED as a unit (CTA, AHU, monobloc) is one, whatever its type says. A LOW 'raccordement' MOSTLY MEANS MISSED UNITS: look for families named CTA, AHU, monobloc, caisson that got no unit role, and add them before sending the user anywhere.
FIRST THE CHECK AND THE LIST, THEN THE CALCULATION. Called with only the token, once your rules are posted with apply_ifc_rules, it computes NOTHING and bills nothing. It walks the networks from every unit and fan and measures the share of the model's air pieces they reach ('raccordement'). Two answers:
CONNECTED (half of the air pieces or more): the COMPLETE list of units and fans ('centrales_et_ventilateurs', each with its number of connected networks) and 'lien_centrales', the CONTROL PAGE ('Network check' in English, 'Contrôle des réseaux' in French) - not a view-only page: every unit in its colour with its networks, where the user checks and CORRECTS the connections (identify or remove a unit, add a virtual AHU, connect or separate two parts, cross a shared plenum) before anything is computed. Ask them to check it FIRST and wait for their answer. There they can also open the calculation page directly, or CLICK the units to compute: they turn red, and 'Send to my AI' copies a new link carrying that choice. Give the user that link, say nothing is computed yet, and that they can tick there or name the units here. Then:
the answer carries 'choix_de_l_utilisateur' (the user ticked on the page): compute EXACTLY those names with units, as its 'consigne' says - do not ask them again;
the user named units, even loosely: map their words onto the EXACT names of the list, say which you picked, and call again with units;
the user asked for the whole model and the list says 'tous_possible' (50 air networks or fewer): call again with all_networks=true;
otherwise show the user the WHOLE list to tick - every unit and fan, however long; never only the main ones. 'Tous' first when it is offered, then one numbered line per unit with its number of connected networks; mark the units connected to nothing. Filter only on what the user said, and then say which filter and how many lines it left out. Call with what they tick.
NOT CONNECTED ('non_raccorde': less than half, or no unit at all): tell the user the sentence of 'A_DIRE_A_L_UTILISATEUR' - « Nous n'avons pas pu connecter les centrales de traitement d'air aux réseaux de votre modèle », in their language - and suggest the pressure-drop page ('lien_pdc'), where they define each network themselves by a start and an end. Nothing is computed. If your rules missed units, fix them and call again. WHAT IS COMPUTED: for each network connected to a chosen unit or fan, the LONGEST path. Networks connected to no unit are not computed here. BEYOND 50 AIR NETWORKS, THE MODEL IS COMPUTED ONE UNIT AT A TIME. Each call computes ONE unit - unit_name, or units with a single name - or the network of ONE piece - network_guid. The whole model, start_role and several units are refused: nothing is computed, and the answer says why. Ask the user which unit, or which piece: on the control page, hovering a piece shows its GUID, and a click ticks a unit. Units the user ticked on the page ('choix_de_l_utilisateur') are asked for: compute them one per call, one after the other. Never pick the units yourself, never go through them all in a row on your own, and never call in parallel (sub-agents, simultaneous calls): the calls on one model run one after the other on the server, and parallel calls only slow the site down for everyone. Call again for the next one the user asks for; what is computed stays, and is not billed again.
YOU SEE A SAMPLE IN THE OVERVIEW, THE WHOLE MODEL HERE. Never choose the units from what read_ifc_overview showed you - one example per type: choose from the list this tool returns.
A REQUEST THE TOOL CANNOT MATCH. Names that match nothing come back under 'non_reconnus', each with the closest names; the names that did match are computed. If NOTHING matched - or the GUID or unit_name is unknown - nothing is computed, whatever the size of the model: the list comes back, with the closest names under 'non_reconnus' and what went wrong under 'demande_non_satisfaite'. Correct the names from the list, or ask the user which one they meant, and call again.
A PIECE INSTEAD OF A UNIT. When the model has no unit, when the unit the user means was not recognised, or when they simply show a piece: network_guid computes the network of any piece - the tool finds where its air starts; end_guid computes one circuit to that end - from start_guid if given, else from the start the tool finds. A start found by the tool comes back under 'depart_trouve' with what made it chosen: say so, and ask the user to check it on the 3D link. The user gets a GUID by hovering a piece on the control page. These work on complex models too: they designate one network.
ONE UNIT BY ITS NAME. unit_name computes the unit or fan of that name, found among all the pieces - units does the same for several. start_guid starts from one part - an air handling unit, a fan, a duct - and computes the network it belongs to, nothing else. The answer says so under 'portee' and lists the model's other units and fans under 'autres_departs': tell the user the result is partial.
From each starting part it keeps ONE CIRCUIT PER BRANCH: the longest path in metres of each branch. From an air handling unit, that is one circuit per network connected to it - supply, return, intake, exhaust.
EACH OF THESE CIRCUITS IS COMPUTED, and becomes a circuit of the model: it has a name, a COLOUR, and a tab on the website. All the circuits of one unit or fan share THAT UNIT'S colour; on the page, its networks show in a light version of it, and networks connected to no unit in grey.
WHAT YOU GET portee what the call covers: the whole model, one role, or one part's network only. circuits one per branch: name, colour, length, its unit, its current type, the flow used at the start and where it came from. NO PRESSURE DROP: see below. autres_arrivees shorter paths, found but NOT computed. lien_3d the calculation page: every unit's networks in its colour, its circuits in a deeper shade. lien_centrales the control page: the units and their networks, where the user checks and corrects the connections and ticks the units to compute. ALWAYS give it, as a full URL, at the top of your answer - also after a calculation: it is the view the user needs most. Never describe it without its link. lien_classeur the Excel workbook of the computed circuits: the supply / return box and the flows are corrected there and everything recalculates. Give it too (a free account is needed to download it). metre the take-off of the whole network.
IF A CIRCUIT IS STILL 'calcul', call again with THE SAME ARGUMENTS a moment later. Nothing is recomputed and nothing is billed again: an identical call only reads. A different velocity or flow is applied to the circuits already there, without a new analysis.
HOW TO USE IT WELL.
Ask the user for the design velocity before calling, or say which one you used. THIS TOOL DOES NOT READ THE FLOW FROM THE MODEL: look for it in the air handling unit's properties with read_ifc_overview and pass it as flow_m3h, one unit at a time - see that argument. Failing that, the flow comes from the design velocity: between two branches, the length-weighted average velocity of the straight ducts equals it, and no duct runs more than 20 % above it. Say which of the two it was.
TWO WAYS TO COMPUTE, AND THE USER CHOOSES. Offer them both, in one short sentence each, before computing:
the network AS MODELLED (the default): flows follow the duct sections and never rise along a circuit, as in a sized network. The pressure drops are NOT returned - see below.
a PRELIMINARY network (preliminary_design=true): nothing is sized yet, so each stretch carries what its own ducts carry at the design velocity, the flow may rise along the circuit, and every fitting is computed at that velocity. The pressure drops ARE returned, because they no longer depend on any flow the user must confirm: they say what a correctly sized circuit with these singularities and this length would reach. Quote them only with that sentence attached. Both compute the same circuits, on the same geometry; only the flows differ. The same circuits can be recomputed either way, by calling again with or without preliminary_design.
YOU ARE NOT GIVEN THE PRESSURE DROPS, ON PURPOSE - except in the preliminary mode above. Until the user has confirmed on the page each circuit's type (supply, return, outdoor air, exhaust) and its flows, the pressure drop is wrong - the tool cannot know either. Never estimate, quote or compute one yourself, not even roughly: say the pressure drops are on the page, once the type and the flows are confirmed.
Every circuit is computed as a SUPPLY circuit until someone says otherwise: the tool cannot tell supply from return. The flow rates do not depend on it - a duct carries what its section allows either way - but the tee coefficients and the design velocity do. If a branch is a return, an intake or an exhaust, SAY SO and tell the user how to set it in the 3D view: hovering the arrow of a circuit shows its type, and each click on that label moves to the next one - supply, return, outdoor air, exhaust. A click on the arrow itself reverses the air direction, which is how the user says at which end the terminal or the louvre sits when the duct has a constant section.
Say that each circuit was chosen BY LENGTH. A shorter path loaded with dampers, bends or silencers can lose more pressure.
BEFORE THE LINK, SAY WHAT THE USER MUST CONFIRM ON THE PAGE - see 'A_CONFIRMER_PAR_L_UTILISATEUR', circuit by circuit: whether each network is supply, return, outdoor air or exhaust (all are computed as supply until the user says otherwise), and the flows (which are estimates from the velocity, which were given). Never leave it out: the figures mean nothing until both are confirmed.
END YOUR ANSWER WITH THE 3D LINK, on its own line, and urge the user to open it - see 'A_DONNER_A_L_UTILISATEUR'. Name each circuit by its unit, its colour and its type - several circuits share a colour. The page is where the calculation is finished: the user sets the flows (a click on the unit, or typed in the table), the velocity, the air direction and the circuit type, deletes a circuit from its tab - its colour goes with it -, adds one by clicking a start and an end part, and downloads the workbook, one editable sheet per circuit.
A FLOW THAT LOOKS WRONG IS AN ESTIMATE, NOT A DEFECT. When none was given, flows come from the design velocity. If you point one out, say in the same breath that the user sets it on the page or in the workbook - see 'debits_et_reglages'.
THE USER'S CHOICES STAND. A circuit they deleted is not computed again: it comes back under 'retires_par_l_utilisateur', and only they can restore it, by tracing it on the page. A circuit they traced by hand is never replaced. So after they have been on the page, call this again before stating any figure - never answer from memory.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The model token, from ifc_upload_result or from the link the user pasted. | |
| units | No | Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. For each network connected to each of them, the longest path is computed. Send the EXACT names when you can: the tool also accepts all the words of a name (« CTA 12 »), a modeller's abbreviation and close spellings - but only with the SAME numbers. Not with start_guid. Beyond 50 air networks: ONE name per call. | |
| end_guid | No | The END of ONE circuit the user wants - a terminal, a louvre, any duct. With start_guid: the circuit from start to end. Alone: the tool finds the start of that network, as for network_guid. Only this circuit is computed, on the path the network walk takes; it never replaces the circuits found by the tool. | |
| flow_m3h | No | Flow rate leaving ONE starting part, m3/h - so give it with start_guid. Over the whole model it would give every unit the same flow, and the call refuses it when there are several: compute the model without it, then call once per unit whose flow you know - its circuits are reused, only their flows change. Every circuit leaving that part carries it on its first stretch, and the flows further on are scaled from it - it sets the real velocity. BEFORE GUESSING, LOOK FOR IT: run read_ifc_overview and read the properties of the air handling unit, the fan or the casing you are starting from - a field named Debit, Flow, Air Flow, Luftmenge or Portata, often under a flow property set. Pass what you find, say where it came from, and convert it to m3/h (a value in m3/s is 3600 times smaller). If the model carries nothing, ASK THE USER rather than inventing one. Omit it only when nobody knows: the flow is then derived from the design velocity: the average velocity of the straight ducts between two branches equals it, none exceeds it by 20 %. | |
| unit_name | No | Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed - except beyond 50 air networks, where nothing is computed and the matches come back: send the exact name of one. No match: it is matched like 'units' (close spellings, same numbers); still nothing: NOTHING is computed, and the list comes back with the closest names. Not with start_guid. | |
| start_guid | No | Leave EMPTY in general. The piece the AIR LEAVES FROM - an air handling unit, a fan, or the duct end where the air enters: circuits are computed from it. A GlobalId from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, from read_ifc_overview (guid_exemple), or clicked by the user on the 3D link. For a piece somewhere IN the network, use network_guid instead: the tool finds the start. With end_guid: the one circuit between the two. Not together with start_role. | |
| start_role | No | Rarely needed. Computes every piece your rules gave this role - centrale_de_traitement_d_air or ventilateur -, like all_networks restricted to one role, and only on a model of 50 air networks or fewer whose units are connected. Prefer units. Not together with start_guid. | |
| all_networks | No | True computes EVERY unit and fan of the list: the longest path of each network connected to them. Networks connected to no unit are not computed - the user traces them on the calculation page, or gives one of their pieces (network_guid). Offered only when the list answer says 'tous_possible': 50 air networks or fewer, units connected. Use it when the user asked for the whole model or ticked 'Tous'. Refused beyond 50 air networks: that model is computed one unit at a time. | |
| network_guid | No | ANY piece of the network the user wants computed - a duct, a terminal, a fitting - when the model has no unit, when the user's unit was not recognised, or when they simply point at the network. The tool walks from it and finds where the air starts: a unit or fan of your rules touching that network (the closest), else a unit found by its IFC class, else the network's largest free duct end. It then computes THAT network only. The start found comes back under 'depart_trouve'. Alone - not with start_guid, end_guid, a name, units or a role. | |
| excluded_guids | No | Parts to close, by GlobalId. Closing a part cuts the walk there: whatever was only reached through it leaves the survey. Use it when the network visibly runs too far - through a plenum shared with another installation, for instance. | |
| max_velocity_m_s | No | Design velocity, in m/s, 0.5 to 12. It sets the flow rate at the start of each circuit when flow_m3h is not given, and the flow after each branch: between two branches, the length-weighted average velocity of the straight ducts equals it, and no duct exceeds it by more than 20 %. Ventilation: 4 to 6 in main ducts, 2 to 3 near the terminals. ASK THE USER rather than guessing. Omit: the model default, 5 m/s. | |
| preliminary_design | No | True when the network is still at a PRELIMINARY stage - not sized yet. Every stretch then carries what its own ducts carry at the design velocity (the flow may rise along the circuit, which a sized network would forbid), and every fitting is computed at that velocity; the flow given at the unit is ignored. This is the ONLY mode where the tool returns pressure drops: they say what a correctly sized circuit with these singularities and this length would reach, not what this network loses. ASK THE USER which of the two they want before calling - see the two modes in this tool's description. Omit it for the normal calculation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-read-only, open-world, idempotent and non-destructive; the description adds billing behaviour ('computes NOTHING and bills nothing', identical calls only read), server-side serialization, persistence of results, that user-deleted circuits are never recomputed, and the deliberate withholding of pressure drops until type and flows are confirmed. These are exactly the traits annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is an extremely long wall of all-caps fragments and run-on paragraphs that repeats the control page, the circuit colouring and the confirmation requirements several times. Section headers help, but the core instruction is not front-loaded and an agent must wade through several thousand words to find the call pattern.
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 12-parameter, multi-turn, user-interactive tool with no output schema, the description covers the full workflow: the connectivity check, the raccordement threshold, the error paths (non_reconnus, demande_non_satisfaite), and an explicit 'WHAT YOU GET' field list. Almost 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?
Schema coverage is 100%, so the baseline is 3; the description nevertheless adds usable meaning beyond the schema — that flow_m3h applies to one starting part only and should be looked up in the IFC properties, that preliminary_design is the only mode returning pressure drops, and the flow-derivation rule when velocity is used. Much is duplicated from the schema, which keeps it out of 5 territory.
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 does state a specific verb and resource — walking the networks from units/fans and computing the longest duct path per branch — and it distinguishes itself from apply_ifc_rules (rules) and read_ifc_overview (a sample only). However, the opening line ('THE CIRCUITS THE FANS OF A MODEL ARE SIZED ON, found without anyone clicking...') is oblique and buries the plain statement of purpose far down the text.
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 covers the token-only first call, the sequencing after apply_ifc_rules, when to use network_guid vs start_guid vs end_guid vs units, the 50-air-network one-unit-at-a-time restriction, and named alternatives (lien_centrales control page, lien_pdc pressure-drop page). It also states when-not conditions (never pick units yourself, never call in parallel, never choose from the overview sample).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DETERMINISTIC: the same inputs always give the same result — from any AI, on any day. Figures come from the standard's tables and formulas, never from a language model's estimate. Every step is auditable.
Deduce the water content of an installation from the expansion vessel already fitted.
WHAT THIS IS FOR. Refurbishment, and site visits with no drawings. Sizing a new vessel, a new pump or a new generator needs the water content, and on an existing installation nobody has it: the drawings are lost, or never matched what was built. The vessel on the wall is the one piece of evidence still standing, and it was chosen from that very figure.
ASK THE OPERATOR FIRST. Whoever filled or refilled the system knows the real figure — from the meter, the filling station, or the maintenance log — and that figure beats any deduction. This tool is what you use when nobody knows, or to check a number that looks wrong. It gets the conversation moving; it does not close it.
HOW. The sizing calculation is run backwards: a trial water content is fed to the EN 12828 sizing, the resulting vessel is compared with the one on site, and the trial is adjusted until they match. The formulas are never rewritten in reverse — the answer cannot contradict the direct calculation, because it is the same code.
WHAT THE ANSWER IS WORTH. A vessel is picked from a catalogue range: a 200 L unit covers everything needing between 141 and 200 L. The result is therefore A RANGE, never a single figure. And an oversized vessel — common — will overstate the content. Compare the range with what you see on site; it does not replace looking.
It also assumes the vessel was sized correctly in the first place. If it was not, the deduction inherits the mistake — which is itself worth knowing: a range far from what the installation plainly holds means the vessel is wrong, and that is a finding in its own right.
| Name | Required | Description | Default |
|---|---|---|---|
| fluid | No | Heat-transfer fluid: 'eau' (Water), 'meg' (MEG), 'mpg' (MPG), 'tyfocor' (TYFOCOR L (MPG)). | water |
| installation | No | 'heating' or 'cooling'. | heating |
| glycol_percent | No | Glycol concentration in %, ignored for water. | |
| pressurisation | No | How pressure is held: 'static' for a plain membrane vessel, 'compressor' for a compressor unit (Compresso and the like), 'pump' for a pump unit. A compressor or pump unit holds the pressure itself, so height and valve setting play no part. | static |
| static_height_m | No | Height of the highest point above the vessel, in metres. Required for 'static' only — a compressor or pump unit does not use it. | |
| vessel_volume_l | Yes | Nominal capacity of the expansion vessel actually installed, in litres — read it on the nameplate. | |
| max_temperature_c | No | HIGHEST temperature the fluid can reach, °C — in extreme conditions, running OR stopped. In heating it is the flow temperature. In cooling it is not the regime at all: a stopped chiller lets the water warm to ambient — 40 °C outdoors, 30 °C indoors in a temperate climate. This is what fixes the expansion. | |
| min_temperature_c | No | LOWEST temperature the fluid can reach, °C — including a breakdown, not just normal running. Indoors, 10 °C. Outdoors, 0 °C, or down to the freezing point of the glycol mix. This is what fixes the reference volume. | |
| valve_setting_bar | No | Safety valve setting, bar. Required for 'static' only. | |
| fill_temperature_c | No | Temperature the water was at when the system was filled, °C. 10 °C is the usual mains temperature indoors. Ask, or state the assumption. | |
| flow_temperature_c | No | Design flow temperature, °C. In heating this is the highest the water reaches. | |
| return_temperature_c | No | Design return temperature, °C. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: the answer is 'A RANGE, never a single figure', oversized vessels overstate the result, and the deduction inherits any original sizing mistake. That is real disclosure of result semantics and failure modes, not repetition.
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?
Sectioned and front-loaded with the differentiator (determinism, reversed sizing), and every heading (WHAT THIS IS FOR / HOW / WHAT THE ANSWER IS WORTH) carries useful content. It is longer than strictly needed and the determinism claim is restated, but there is little true filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no output schema, the description supplies the missing result-shape information (a range), the key assumption (vessel was correctly sized) and auditability. It does not describe output structure in more detail, but combined with a fully documented schema this is close to 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 description coverage is 100%, so the schema already documents all 12 parameters, including defaults, ranges and the static/compressor distinction. The description adds conceptual context (what fixes expansion, what fixes reference volume) but no parameter-level semantics beyond the schema, 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?
States a specific verb and resource — deduce the water content of an installation from the fitted expansion vessel — and immediately frames itself against the forward calculation ('the sizing calculation is run backwards'), which is exactly the sibling size_expansion_vessel. An agent can identify what it does and how it differs from the forward sizing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit sequencing: 'ASK THE OPERATOR FIRST' identifies the preferred source, and 'This tool is what you use when nobody knows, or to check a number that looks wrong' gives a precise when-to-use condition. It also states when it is appropriate (refurbishment, site visits with no drawings).
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.
read_ifc_overview2 fields changedInput schema / properties / familiesAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Leave EMPTY on the first call. Then, to read EVERY property of some families, their 'famille' names from the first answer - at most 12 per call. Only the detail asked for comes back.",
+ "title": "Families"
+}Input schema / properties / property_catalogueAdded value: +{
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "True lists every property of the model once, by property set, with an example value - to find which 'PropertySet.Property' holds a size or a flow. Only the catalogue comes back.",
+ "title": "Property Catalogue"
+}trace_duct_circuits1 field changedInput schema / properties / preliminary_designAdded value: +{
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "True when the network is still at a PRELIMINARY stage - not sized yet. Every stretch then carries what its own ducts carry at the design velocity (the flow may rise along the circuit, which a sized network would forbid), and every fitting is computed at that velocity; the flow given at the unit is ignored. This is the ONLY mode where the tool returns pressure drops: they say what a correctly sized circuit with these singularities and this length would reach, not what this network loses. ASK THE USER which of the two they want before calling - see the two modes in this tool's description. Omit it for the normal calculation.",
+ "title": "Preliminary Design"
+}trace_duct_circuits5 fields changedInput schema / properties / all_networks / descriptionPrevious value: -"True computes the WHOLE model: every unit and fan, and a supposed start for each network none of them serves. Offered only when the list answer says 'tous_possible': 50 air networks or fewer. Use it when the user asked for the whole model or ticked 'Tous'. Refused beyond 50 air networks: that model is computed one network at a time."New value: +"True computes EVERY unit and fan of the list: the longest path of each network connected to them. Networks connected to no unit are not computed - the user traces them on the calculation page, or gives one of their pieces (network_guid). Offered only when the list answer says 'tous_possible': 50 air networks or fewer, units connected. Use it when the user asked for the whole model or ticked 'Tous'. Refused beyond 50 air networks: that model is computed one unit at a time."Input schema / properties / network_guid / descriptionPrevious value: -"ANY piece of the network the user wants computed - a duct, a terminal, a fitting - when the model has no unit, when the user's unit was not recognised, or when they simply point at the network. The tool walks from it and finds where the air starts: a unit or fan of your rules touching that network (the closest), else a unit found by its IFC class, else the network's largest free duct end. It then computes THAT network only. The start found comes back under 'depart_trouve'. Alone - not with start_guid, end_guid, a name, systems, units or a role."New value: +"ANY piece of the network the user wants computed - a duct, a terminal, a fitting - when the model has no unit, when the user's unit was not recognised, or when they simply point at the network. The tool walks from it and finds where the air starts: a unit or fan of your rules touching that network (the closest), else a unit found by its IFC class, else the network's largest free duct end. It then computes THAT network only. The start found comes back under 'depart_trouve'. Alone - not with start_guid, end_guid, a name, units or a role."Input schema / properties / start_role / descriptionPrevious value: -"Rarely needed. Computes every piece your rules gave this role - centrale_de_traitement_d_air or ventilateur -, like all_networks restricted to one role, and only on a model of 50 air networks or fewer. Prefer systems and units. Not together with start_guid."New value: +"Rarely needed. Computes every piece your rules gave this role - centrale_de_traitement_d_air or ventilateur -, like all_networks restricted to one role, and only on a model of 50 air networks or fewer whose units are connected. Prefer units. Not together with start_guid."Input schema / properties / systemsRemoved value: -{
- "anyOf": [
- {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Systems to compute, by name - from 'systemes' of the list answer, or from read_ifc_networks. Each brings in the WHOLE air handling unit or fan that serves it (supply, return, outdoor air, exhaust); a system no unit serves starts from a supposed start. Send the EXACT names when you can: the tool also accepts all the words of a name (« SYS07 REP »), a modeller's abbreviation (« extraction » for « EXT ») and close spellings - but only with the SAME numbers. Not with start_guid. Refused beyond 50 air networks: start from the unit that serves the system, by its name.",
- "title": "Systems"
-}Input schema / properties / units / descriptionPrevious value: -"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. Same matching as systems. Can be combined with systems. Not with start_guid. Beyond 50 air networks: ONE name per call."New value: +"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. For each network connected to each of them, the longest path is computed. Send the EXACT names when you can: the tool also accepts all the words of a name (« CTA 12 »), a modeller's abbreviation and close spellings - but only with the SAME numbers. Not with start_guid. Beyond 50 air networks: ONE name per call."trace_duct_circuits3 fields changedInput schema / properties / end_guidAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "The END of ONE circuit the user wants - a terminal, a louvre, any duct. With start_guid: the circuit from start to end. Alone: the tool finds the start of that network, as for network_guid. Only this circuit is computed, on the path the network walk takes; it never replaces the circuits found by the tool.",
+ "title": "End Guid"
+}Input schema / properties / network_guidAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ANY piece of the network the user wants computed - a duct, a terminal, a fitting - when the model has no unit, when the user's unit was not recognised, or when they simply point at the network. The tool walks from it and finds where the air starts: a unit or fan of your rules touching that network (the closest), else a unit found by its IFC class, else the network's largest free duct end. It then computes THAT network only. The start found comes back under 'depart_trouve'. Alone - not with start_guid, end_guid, a name, systems, units or a role.",
+ "title": "Network Guid"
+}Input schema / properties / start_guid / descriptionPrevious value: -"Leave EMPTY in general. Give a GlobalId only when the user asks about ONE unit or one network: an air handling unit, a fan, or any duct of it - from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, or from read_ifc_overview (guid_exemple). Only that part's network is then computed, and the answer lists the units and fans left out. Not together with start_role."New value: +"Leave EMPTY in general. The piece the AIR LEAVES FROM - an air handling unit, a fan, or the duct end where the air enters: circuits are computed from it. A GlobalId from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, from read_ifc_overview (guid_exemple), or clicked by the user on the 3D link. For a piece somewhere IN the network, use network_guid instead: the tool finds the start. With end_guid: the one circuit between the two. Not together with start_role."trace_duct_circuits4 fields changedInput schema / properties / all_networks / descriptionPrevious value: -"True computes the WHOLE model: every unit and fan, and a supposed start for each network none of them serves. Offered only when the list answer says 'tous_possible': 50 air networks or fewer. Use it when the user asked for the whole model or ticked 'Tous'. Beyond 50 the call returns the list again."New value: +"True computes the WHOLE model: every unit and fan, and a supposed start for each network none of them serves. Offered only when the list answer says 'tous_possible': 50 air networks or fewer. Use it when the user asked for the whole model or ticked 'Tous'. Refused beyond 50 air networks: that model is computed one network at a time."Input schema / properties / systems / descriptionPrevious value: -"Systems to compute, by name - from 'systemes' of the list answer, or from read_ifc_networks. Each brings in the WHOLE air handling unit or fan that serves it (supply, return, outdoor air, exhaust); a system no unit serves starts from a supposed start. Send the EXACT names when you can: the tool also accepts all the words of a name (« SYS07 REP »), a modeller's abbreviation (« extraction » for « EXT ») and close spellings - but only with the SAME numbers. Not with start_guid."New value: +"Systems to compute, by name - from 'systemes' of the list answer, or from read_ifc_networks. Each brings in the WHOLE air handling unit or fan that serves it (supply, return, outdoor air, exhaust); a system no unit serves starts from a supposed start. Send the EXACT names when you can: the tool also accepts all the words of a name (« SYS07 REP »), a modeller's abbreviation (« extraction » for « EXT ») and close spellings - but only with the SAME numbers. Not with start_guid. Refused beyond 50 air networks: start from the unit that serves the system, by its name."Input schema / properties / unit_name / descriptionPrevious value: -"Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed. No match: it is matched like 'units' (close spellings, same numbers); still nothing: NOTHING is computed, and the list comes back with the closest names. Not with start_guid."New value: +"Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed - except beyond 50 air networks, where nothing is computed and the matches come back: send the exact name of one. No match: it is matched like 'units' (close spellings, same numbers); still nothing: NOTHING is computed, and the list comes back with the closest names. Not with start_guid."Input schema / properties / units / descriptionPrevious value: -"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. Same matching as systems. Can be combined with systems. Not with start_guid."New value: +"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. Same matching as systems. Can be combined with systems. Not with start_guid. Beyond 50 air networks: ONE name per call."trace_duct_circuits1 field changedInput schema / properties / unit_name / descriptionPrevious value: -"Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed. No match: the WHOLE model is computed instead, and the answer says why and lists the known names. Leave it empty for the whole model. Not with start_guid."New value: +"Only when the user asks about ONE unit or fan: its name, or a part of it - « CTA 12 », « AHU-Supply-L2 ». The tool looks it up among EVERY piece your rules gave the role centrale_de_traitement_d_air or ventilateur, case and accents ignored, all words required. Several matches: all are computed. No match: it is matched like 'units' (close spellings, same numbers); still nothing: NOTHING is computed, and the list comes back with the closest names. Not with start_guid."trace_duct_circuits5 fields changedInput schema / properties / all_networksAdded value: +{
+ "anyOf": [
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "True computes the WHOLE model: every unit and fan, and a supposed start for each network none of them serves. Offered only when the list answer says 'tous_possible': 50 air networks or fewer. Use it when the user asked for the whole model or ticked 'Tous'. Beyond 50 the call returns the list again.",
+ "title": "All Networks"
+}Input schema / properties / start_guid / descriptionPrevious value: -"Leave EMPTY to compute the whole model. Give a GlobalId only when the user asks about ONE unit or one network: an air handling unit, a fan, or any duct of it - from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, or from read_ifc_overview (guid_exemple). Only that part's network is then computed, and the answer lists the units and fans left out. Not together with start_role."New value: +"Leave EMPTY in general. Give a GlobalId only when the user asks about ONE unit or one network: an air handling unit, a fan, or any duct of it - from 'equipements' in the answer of apply_ifc_rules, from read_ifc_networks, or from read_ifc_overview (guid_exemple). Only that part's network is then computed, and the answer lists the units and fans left out. Not together with start_role."Input schema / properties / start_role / descriptionPrevious value: -"Which pieces to start from, by the role your rules gave them. Default all: every centrale_de_traitement_d_air (air handling units, monoblocs, ventilation casings) and every ventilateur (fans), units first, then a supposed start for each network none of them serves - the whole model. Give one of these two names to keep only that role. Needs apply_ifc_rules first; without rules the call says what to post. A fan that lies in a unit's network is not explored twice. Not together with start_guid."New value: +"Rarely needed. Computes every piece your rules gave this role - centrale_de_traitement_d_air or ventilateur -, like all_networks restricted to one role, and only on a model of 50 air networks or fewer. Prefer systems and units. Not together with start_guid."Input schema / properties / systems / descriptionPrevious value: -"Systems to compute, by name - from 'systemes' of a 'trop_complexe' answer, or from read_ifc_networks. Each brings in the WHOLE air handling unit or fan that serves it (supply, return, outdoor air, exhaust); a system no unit serves starts from a supposed start. Send the EXACT names when you can: the tool also accepts all the words of a name (« SYS07 REP »), a modeller's abbreviation (« extraction » for « EXT ») and close spellings - but only with the SAME numbers. Not with start_guid."New value: +"Systems to compute, by name - from 'systemes' of the list answer, or from read_ifc_networks. Each brings in the WHOLE air handling unit or fan that serves it (supply, return, outdoor air, exhaust); a system no unit serves starts from a supposed start. Send the EXACT names when you can: the tool also accepts all the words of a name (« SYS07 REP »), a modeller's abbreviation (« extraction » for « EXT ») and close spellings - but only with the SAME numbers. Not with start_guid."Input schema / properties / units / descriptionPrevious value: -"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of a 'trop_complexe' answer, or from 'equipements' of apply_ifc_rules. Same matching as systems. Can be combined with systems. Not with start_guid."New value: +"Air handling units or fans to compute, by name - from 'centrales_et_ventilateurs' of the list answer, or from 'equipements' of apply_ifc_rules. Same matching as systems. Can be combined with systems. Not with start_guid."Design, solve and simulate HVAC systems from real components, weather years and buildings.
27 engineering compliance and calculation tools for the built environment (UK, EU, UAE).
Heating, ventilation and energy engineering calculations and diagnostics for AI agents.
Electrical single-line and multi-line diagrams: build, check (NF C 15-100, IEC 60364), draw, PDF.
Add one secure layer between your agents and this server.
