The New Engineer — HVAC

read_ifc_overview

Read-onlyIdempotent

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.

Input Schema

Name	Required	Description
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 1, 2026

addedInput schema / properties / families

Added 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"
+}

addedInput schema / properties / property_catalogue

Added 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"
+}

AddedOct 2, 2026

TDQS

A4.2/5.0

Behavior5/5

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.

Conciseness2/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines5/5

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.

All The New Engineer — HVAC tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?