This server lets an AI assistant build, run, and analyze CFAST (Consolidated Fire and Smoke Transport) fire simulations through conversation.
Model Creation & Configuration
create_model – Create a new simulation with an initial compartment, title, dimensions, duration, and ambient conditions
update_simulation – Update simulation-level parameters (title, duration, temperatures, humidity)
Building the Model
add_material / update_material – Define thermophysical surface materials (conductivity, density, specific heat, thickness, emissivity)
add_compartment / update_compartment – Add rooms with dimensions, position, and surface material assignments
add_wall_vent / update_wall_vent – Add doors, windows, or openings between compartments or to the outside
add_ceiling_floor_vent / update_ceiling_floor_vent – Add vertical flow openings between stacked compartments
add_mechanical_vent / update_mechanical_vent – Add fan-driven ventilation systems
add_fire / update_fire – Define time-dependent fires with HRR curves, fuel composition, and species yields
add_device / update_device – Add targets (PLATE, CYLINDER) or detectors (heat, smoke, sprinkler)
add_surface_connection / update_surface_connection – Define heat transfer through solid boundaries between compartments
Inspection & File Access
inspect_model – Get a model summary, optionally including the raw CFAST .in input file
get_model_files – Locate on-disk files (.in, .csv, logs) for a model
Running & Analyzing Results
run_model – Execute the CFAST simulation with a configurable timeout
get_results – Retrieve bounded previews or per-column statistics (min, max, final value, time of max) from output sets such as compartment temperatures, device readings, vent flows, and diagnostics
Models live in memory during the server session; files are written to a temporary directory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CFAST MCP Create a 5x5x3m room with a 100kW fire and run simulation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CFAST MCP is an MCP server that lets an AI assistant build, run, and analyze CFAST (Consolidated Fire and Smoke Transport, NIST) fire simulations through conversation. It is built on top of PyCFAST and exposes the CFAST model as a set of tools. The AI assistant is able to create a model, add compartments, materials, vents, fires and devices step by step, run CFAST, and make summaries of the results.
A live demo using the MCP server is available on Hugging Face Spaces. You can try it out without any installation:
Related MCP server: BULC Building Designer
Ask your assistant something like:
Create a 4 m × 3 m × 2.5 m room with a door (0.9 × 2 m) to the outside and a fire growing to 1 MW in 300 s. Run it and give me the peak upper-layer temperature then show me the folder where you create the file, so I can inspect it.
Results will probably look like this:
Group | Tools |
Create & configure |
|
Components |
|
Inspect |
|
Run & results |
|
Results are returned to the AI assistant as small text summaries. The generated files (.in, output .csv, logs) are written in a temporary directory while the session is active. Use get_model_files to locate them if you want to open them directly.
Note: models live in memory for the lifetime of the server process. Restarting the server (or your MCP client) will delete them.
Requires Python 3.10+ and CFAST 7.7.0+.
Install uv, then add cfast-mcp directly in your client configuration:
{
"mcpServers": {
"cfast": {
"command": "uvx",
"args": ["cfast-mcp"],
"env": { "CFAST": "/path/to/your/cfast/executable" }
}
}
}If you use Claude Code, a single command registers the server:
claude mcp add cfast -e CFAST=/path/to/your/cfast/executable -- cfast-mcpCreate a virtual environment and install from PyPI:
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install cfast-mcpThen add cfast-mcp to your client configuration:
{
"mcpServers": {
"cfast": {
"command": "cfast-mcp",
"env": { "CFAST": "/path/to/your/cfast/executable" }
}
}
}Download and install CFAST from the NIST CFAST website or the CFAST GitHub repository. Follow the installation instructions for your operating system and ensure cfast is available in your PATH. If CFAST is installed in a non-standard location, you can manually specify the path by setting the CFAST environment variable to point to the CFAST executable.
export CFAST="/path/to/your/cfast/executable" # Linux/macOS
set CFAST="C:\path\to\cfast.exe" # Windows (cmd)
$env:CFAST="C:\path\to\cfast.exe" # Windows (PowerShell)git clone https://github.com/bewygs/cfast-mcp.git
cd cfast-mcp
uv sync --extra dev # install dev dependencies
uv run pytest # run tests
uv run ruff check --fix . # lint
uv run mypy src/ # type-checkAdd a ceiling/floor vent (vertical flow opening) between compartments.
Vertical flow vents connect compartments stacked in elevation, or a compartment to the outside (e.g. a hole in a roof). Both compartments must already exist in the model; comp_bottom may be "OUTSIDE".
model_id : str Id of the model to modify. id : str Unique name of the vent. comp_top : str Top compartment id, where the vent is in the floor. comp_bottom : str Bottom compartment id, where the vent is in the ceiling, or "OUTSIDE" for the exterior. area : float Cross-sectional area of the vent opening. Default units: m². type : str, optional Type of ceiling/floor vent: FLOOR or CEILING. Default value: FLOOR. shape : str, optional Shape factor used to compute the effective diameter and flow coefficients: ROUND or SQUARE. Default value: ROUND. offsets : list[float] or None, optional For visualization only, [x_offset, y_offset] horizontal distances between the center of the vent and the origin of the X and Y axes in the upper compartment. Default units: m, default value: [0, 0] m.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| area | Yes | ||
| type | No | FLOOR | |
| shape | No | ROUND | |
| offsets | No | ||
| comp_top | Yes | ||
| model_id | Yes | ||
| comp_bottom | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, but the description covers what the tool does (adds a vent), parameters with defaults, and return value (confirmation, model summary, warnings). Lacks explicit mention of side effects or destructive actions, but given the nature, it is adequate.
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?
Well-structured docstring with sections for description, parameters, and returns. Each sentence adds value, no redundancy. Appropriate length for the complexity.
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?
Covers all 8 parameters (5 required) with units and defaults, explains use case (vertical flow), specifies prerequisites (compartments exist), and describes return type. Complete given no annotations and no output schema in structured data.
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 has 0% description coverage, but the description provides detailed parameter documentation including units, defaults, allowed values (e.g., FLOOR/CEILING, ROUND/SQUARE), and clarifies that offsets are for visualization only. Adds full meaning beyond schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it adds a ceiling/floor vent (vertical flow opening) between compartments. It distinguishes from siblings like add_wall_vent (horizontal) and add_mechanical_vent (mechanical) by specifying vertical orientation.
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?
Provides context that vents connect stacked compartments or a compartment to outside, and that compartments must exist. Does not explicitly mention when not to use or give equivalent tools, but the vertical vs horizontal distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a compartment to a model.
Any surface material id given (ceiling, wall, floor) must already exist in the model — add it first with add_material. If the thermophysical properties of a surface are not included, CFAST treats it as adiabatic (no heat transfer).
model_id : str Id of the model to modify. id : str Unique alphanumeric name of the compartment, referenced later by fires and wall vents. width : float Width of the compartment as measured on the X axis from its origin. Default units: m. depth : float Depth of the compartment as measured on the Y axis from its origin. Default units: m. height : float Height of the compartment as measured on the Z axis from its origin. Default units: m. ceiling_mat_id : str or None, optional Material id defining the ceiling surface. Default value: Off. ceiling_thickness : float or None, optional Thickness of the ceiling surface. Default units: m, default value: thickness of the material. wall_mat_id : str or None, optional Material id defining the wall surfaces. Default value: Off. wall_thickness : float or None, optional Thickness of the wall surfaces. Default units: m, default value: thickness of the material. floor_mat_id : str or None, optional Material id defining the floor surface. Default value: Off. floor_thickness : float or None, optional Thickness of the floor surface. Default units: m, default value: thickness of the material. origin_x : float, optional Absolute x coordinate of the lower, left, front corner of the room. Negative values are not allowed. Default units: m, default value: 0.0 m. origin_y : float, optional Absolute y coordinate of the lower, left, front corner of the room. Negative values are not allowed. Default units: m, default value: 0.0 m. origin_z : float, optional Height of the floor of the compartment with respect to the station elevation. Default units: m, default value: 0.0 m.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| depth | Yes | ||
| width | Yes | ||
| height | Yes | ||
| model_id | Yes | ||
| origin_x | No | ||
| origin_y | No | ||
| origin_z | No | ||
| wall_mat_id | No | ||
| floor_mat_id | No | ||
| ceiling_mat_id | No | ||
| wall_thickness | No | ||
| floor_thickness | No | ||
| ceiling_thickness | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses key behaviors: material defaults, units, negative value restrictions for origins, and the return type. It lacks some details like error handling but is transparent overall.
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 well-structured with a brief intro and detailed parameter list. While it is relatively long, every sentence adds value and is appropriately front-loaded. Slightly more conciseness could be achieved, but it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 14 parameters, lack of annotations, and the presence of an output schema, the description covers prerequisites, default behaviors, constraints, and return values. It is complete and leaves no significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides extensive explanations for all 14 parameters, including defaults, units, constraints, and meaning. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add a compartment to a model.' It also distinguishes from sibling tools like add_material by noting that surface materials must exist first and can be added with add_material.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines, such as requiring surface materials to exist beforehand and the default adiabatic behavior. It does not explicitly state when not to use the tool, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a device (target or detector) to a compartment of a model.
Devices are either targets (PLATE, CYLINDER), which heat up and report temperature, or detectors (HEAT_DETECTOR, SMOKE_DETECTOR, SPRINKLER). The compartment comp_id must already exist. Required fields depend on the type: targets need material_id (already added with add_material) and exactly one of normal or surface_orientation; HEAT_DETECTOR and SPRINKLER need setpoint and rti (SPRINKLER also spray_density).
model_id : str Id of the model to modify. id : str Unique name of the target or detector. comp_id : str Compartment in which the device is located. location : list[float] Position [x, y, z] as distances from the left wall, the front wall, and the floor. Default units: m. type : str One of PLATE, CYLINDER (targets), HEAT_DETECTOR, SMOKE_DETECTOR, SPRINKLER (detectors). material_id : str or None, optional What the target is made of; must already exist in the model. Required for target types (PLATE, CYLINDER). surface_orientation : str or None, optional Predefined surface orientation for targets: CEILING, FRONT WALL, BACK WALL, LEFT WALL, RIGHT WALL or FLOOR. Provide exactly one of surface_orientation or normal for a target. normal : list[float] or None, optional Unit vector [nx, ny, nz] perpendicular to the exposed target surface (e.g. [0, 0, 1] faces the ceiling). Provide exactly one of normal or surface_orientation for a target. thickness : float or None, optional Thickness of the target material; if None, the material's value is used. Default units: m. temperature_depth : float, optional Depth at which the internal target temperature is reported. With depth_units="M" (default) an absolute depth in meters from the front surface, which must be > 0 and less than the material thickness; otherwise a fraction of the thickness in [0, 1]. Default value: 0.5. depth_units : str, optional Units for temperature_depth: "M" for meters. Default value: M. setpoint : float or None, optional Temperature at or above which the link activates. Default units: °C. Required for HEAT_DETECTOR and SPRINKLER. rti : float or None, optional Response Time Index for the sprinkler or detector. Default units: (m·s)^(1/2). Required for HEAT_DETECTOR and SPRINKLER. obscuration : float, optional Obscuration at or above which a SMOKE_DETECTOR activates. Default units: %/m, default value: 23.93 %/m. spray_density : float or None, optional Amount of water dispersed by a sprinkler. Default units: m/s. Required for SPRINKLER.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| rti | No | ||
| type | Yes | ||
| normal | No | ||
| comp_id | Yes | ||
| location | Yes | ||
| model_id | Yes | ||
| setpoint | No | ||
| thickness | No | ||
| depth_units | No | M | |
| material_id | No | ||
| obscuration | No | ||
| spray_density | No | ||
| temperature_depth | No | ||
| surface_orientation | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses prerequisites (compartment must exist, material must be added via add_material), parameter dependencies (exactly one of normal or surface_orientation for targets), and default values/units (e.g., temperature_depth default 0.5, depth_units default 'M'). It does not explicitly mention error handling or idempotency, but covers most behavioral aspects thoroughly.
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 well-structured with a clear introductory sentence, a bullet-like list of parameters, and a return section. It is comprehensive but slightly verbose; given the complexity (15 parameters), the length is justified. It could be more concise by grouping common info, but it remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters, conditional requirements, multiple device types) and the presence of an output schema, the description is remarkably complete. It covers prerequisites, parameter dependencies, default values, units, and return format. It does not delve into error cases but provides enough context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It does so excellently by explaining each parameter in depth: location coordinates, units, conditional requirements (e.g., material_id only for targets), default values, and the meaning of temperature_depth and depth_units. This far exceeds the minimal schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a device (target or detector) to a compartment, distinguishing between target and detector types. It specifies the device subtypes (PLATE, CYLINDER, etc.) and notes the prerequisite that the compartment must already exist. This clearly differentiates from sibling tools like 'add_compartment' or 'update_device'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed guidance on when to use each parameter based on device type (e.g., material_id for targets, setpoint for detectors). It explains which parameters are required for which type. However, it does not explicitly state when not to use this tool (e.g., for updating an existing device, use 'update_device'). The guidelines are clear but lack explicit exclusionary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a fire to a compartment of a model.
A fire in CFAST is specified via a time-dependent heat release rate (HRR). The compartment comp_id must already exist in the model. Fire properties are linearly interpolated between specified time points; if the simulation time is longer than the total duration of the fire, the final values are continued until the end of the simulation.
model_id : str Id of the model to modify. id : str Unique name of the fire instance. comp_id : str Name of the compartment where the fire occurs. fire_id : str Unique name of the fire definition (fuel composition and HRR curve). May be the same as id. location : list[float] Position [x, y] of the center of the base of the fire relative to the front left corner of the compartment. Default units: m. data_table : list[list[float]] Time-dependent fire properties: one row per time point, with columns [TIME (s), HRR (kW), HEIGHT (m), AREA (m²), CO_YIELD, SOOT_YIELD, HCN_YIELD, HCL_YIELD, TRACE_YIELD], yields in kg/kg. Example for a fire growing to 1000 kW at 300 s: [[0, 0, 0, 0.3, 0.005, 0.02, 0, 0, 0], [300, 1000, 0, 0.3, 0.005, 0.02, 0, 0, 0]]. carbon : float, optional Number of carbon atoms in the fuel molecule. Default value: 1. chlorine : float, optional Number of chlorine atoms in the fuel molecule; assumed to completely react to form HCl. Default value: 0. hydrogen : float, optional Number of hydrogen atoms in the fuel molecule. Default value: 4. nitrogen : float, optional Number of nitrogen atoms in the fuel molecule; assumed to completely react to form HCN. Default value: 0. oxygen : float, optional Number of oxygen atoms in the fuel molecule. Default value: 0. heat_of_combustion : float, optional The energy released per unit mass of fuel consumed. Default units: kJ/kg, default value: 50000 kJ/kg. radiative_fraction : float, optional The fraction of the combustion energy that is emitted in the form of thermal radiation. Default units: none, default value: 0.35.
str Confirmation, the updated model summary, and any warnings (for example a fire located outside the compartment footprint).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| carbon | No | ||
| oxygen | No | ||
| comp_id | Yes | ||
| fire_id | Yes | ||
| chlorine | No | ||
| hydrogen | No | ||
| location | Yes | ||
| model_id | Yes | ||
| nitrogen | No | ||
| data_table | Yes | ||
| heat_of_combustion | No | ||
| radiative_fraction | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers thorough behavioral details: time-dependent HRR specification, linear interpolation, continuation of final values, and warning if fire is outside compartment. No contradictions.
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 well-structured with sections for parameters and return value, using bullet points and an example. While lengthy, every sentence adds value given the tool's complexity, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, complex nested data type), the description covers all parameters, explains the return value, and warns about edge cases. No gaps remain despite the absence of annotations.
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 0%, yet the description provides detailed explanations for all 13 parameters, including defaults, units, and an explicit example for the complex 'data_table' parameter. This adds significant meaning beyond the schema's type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add') and resource ('fire') and specifies the context of adding to a compartment of a model. It distinguishes the tool from the sibling 'update_fire' by indicating this is for new additions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides important context: the compartment must already exist, simulation interpolation behavior, and continuation of fire properties. However, it does not explicitly mention when to use this tool versus the sibling 'update_fire' or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a material to a model.
A compartment can reference this material by id for its ceiling, wall or floor surfaces, or a target.
model_id : str Id of the model to modify, as returned by create_model. id : str A one-word (no more than 8 characters) unique identifier for the material, used in other inputs to reference it. material : str A descriptive name for the material. conductivity : float Thermal conductivity for the material. Default units: W/(m·K). density : float Density for the material. Default units: kg/m³. specific_heat : float Specific heat for the material. Default units: kJ/(kg·K). thickness : float Thickness of the material. Default units: m. emissivity : float, optional Emissivity of the material surface; the fraction of radiation that is absorbed by the material. Default units: none, default value: 0.9.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| density | Yes | ||
| material | Yes | ||
| model_id | Yes | ||
| thickness | Yes | ||
| emissivity | No | ||
| conductivity | Yes | ||
| specific_heat | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits like id uniqueness constraints, model mutation details, or side effects (e.g., overwriting existing material). Only parameter definitions are given.
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 structured with sections and bullet points, making it readable. While some repetition exists (e.g., parameter descriptions in docstring style), it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (context signal), the description's mention of return as confirmation/summary/warnings is sufficient. All 8 parameters are explained, and the overall context for adding a material is covered.
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 description adds significant value to each parameter beyond the schema: units for conductivity, density, specific heat, thickness; default value and units for emissivity; character limit for id. This compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a material to a model, and mentions how compartments can reference it by ID. This distinguishes it from update_material, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly suggests using this tool before referencing materials in compartments or targets, but does not explicitly contrast with update_material or provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a mechanical vent between two compartments.
Mechanical ventilation moves air at a user-specified volume flow between two compartments, or between a compartment and the outside. Both compartments must already exist in the model; comp_from or comp_to may be "OUTSIDE".
model_id : str Id of the model to modify. id : str Unique name of the mechanical ventilation system. comp_from : str Compartment from which the fan flow originates, or "OUTSIDE". comp_to : str Compartment to which the fan flow terminates, or "OUTSIDE". flow : float Constant volumetric flow rate of the fan. Default units: m³/s. area : list[float] or None, optional Cross-sectional area of the opening for each connection [area_from, area_to]. Default units: m², default value: [0, 0] m². heights : list[float] or None, optional Height of the midpoint of the duct opening above the floor for each connection [height_from, height_to]. Default units: m, default value: [0, 0] m. orientations : list[str] or None, optional Flow orientation for each connection, HORIZONTAL or VERTICAL. A horizontal diffuser implies vertical flow through the ceiling or floor; a vertical diffuser implies horizontal flow through a wall. Default value: ["VERTICAL", "VERTICAL"]. cutoffs : list[float] or None, optional Pressure control values [begin_drop_off_pressure, zero_flow_pressure]: above the first the flow drops off, above the second it is zero. Default units: Pa, default value: [200, 300] Pa. offsets : list[float] or None, optional For visualization only, [x_offset, y_offset] horizontal distances between the center of the vent and the origin of the X and Y axes in the first compartment. Default units: m, default value: [0, 0] m. filter_time : float, optional Time at which mechanical vent filtering begins. Default units: s, default value: 0 s. filter_efficiency : float, optional Portion of soot and trace species mass removed from the flow, specified as a percentage (0-100). Default value: 0.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| area | No | ||
| flow | Yes | ||
| comp_to | Yes | ||
| cutoffs | No | ||
| heights | No | ||
| offsets | No | ||
| model_id | Yes | ||
| comp_from | Yes | ||
| filter_time | No | ||
| orientations | No | ||
| filter_efficiency | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains parameters and return value but does not disclose side effects, error conditions, or whether the operation is reversible. Lacks behavioral details like model mutation implications.
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?
Structured with Parameters and Returns sections, front-loads purpose. Slightly verbose in parameter descriptions but each sentence provides necessary information. Efficient overall.
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 12-parameter tool with no annotations and no output schema (description provides return type), the description covers purpose, all parameters, and return value. Adequately 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 0%, so description fully compensates. Each parameter is described with units, defaults, valid options (e.g., 'OUTSIDE'), and meaning, adding significant value 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 clearly states the verb 'Add' and resource 'mechanical vent', specifies it is between two compartments or between a compartment and outside, and distinguishes from sibling vent tools by mentioning mechanical (fan-forced) ventilation.
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?
Provides precondition that compartments must exist and allows 'OUTSIDE', but does not explicitly state when to use this vs other vent types (e.g., natural vents). Offers some context but no exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a surface connection between compartments.
Surface connections transfer heat through solid boundaries between two compartments. Both compartments must already exist in the model. Unlike other components, a surface connection has no id; refer to it by its position (index) when updating. For WALL connections you should add one in each direction (comp_id -> comp_ids and comp_ids -> comp_id).
model_id : str Id of the model to modify. conn_type : str Type of connection: WALL for horizontal heat transfer through vertical surfaces, FLOOR for vertical heat transfer through horizontal surfaces. comp_id : str First compartment id. For WALL, the compartment whose wall area fraction is given; for FLOOR, the top compartment (through its floor). comp_ids : str Second compartment id. For FLOOR, the bottom compartment (through its ceiling). fraction : float or None, optional Fraction (0-1) of the first compartment's vertical surface area that connects the two compartments. Required for WALL connections; must be None for FLOOR connections.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| comp_id | Yes | ||
| comp_ids | Yes | ||
| fraction | No | ||
| model_id | Yes | ||
| conn_type | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes key behavioral traits: heat transfer, id-less referencing, fraction constraints for WALL vs FLOOR. Could mention whether adding overwrites or duplicates connections.
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?
Well-structured with brief intro, parameter definitions, and return info. No wasted words.
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?
Covers purpose, prerequisites, parameters, and returns. Could mention any limits on number of connections or interactions with other components.
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?
All five parameters are described with detailed semantics, including constraints on fraction and role of comp_id/comp_ids for different connection types, compensating for 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Add' and resource 'surface connection'. Explanation of heat transfer through solid boundaries distinguishes it from sibling tools like add_wall_vent or add_ceiling_floor_vent.
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 states prerequisites (compartments must exist), gives directionality advice for WALL connections, and notes that no ID is used (refer by index).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a wall vent (door, window or opening) between two compartments.
Wall vents connect compartments that physically overlap in elevation, or connect a compartment to the outside. Both compartments must already exist in the model; comp_b may be "OUTSIDE" to vent to the exterior. All specifications of the vent are made relative to the floor of the first compartment.
model_id : str Id of the model to modify. id : str Unique name of the vent. comp_a : str First compartment id; the reference for all vent specifications. comp_b : str Second compartment id, or "OUTSIDE" for the exterior. bottom : float Position of the bottom of the opening relative to the floor of the first compartment. Default units: m. height : float Height of the opening relative to the bottom of the opening. Default units: m. width : float Width of the opening. Default units: m. face : str The wall on which the vent is positioned. Choices are FRONT, REAR, LEFT, RIGHT; Front and Rear faces are parallel to the X axis, Left and Right to the Y axis. offset : float, optional For visualization only, the horizontal distance between the near edge of the vent and the origin of the axis defined by the selected face. Default units: m, default value: 0 m.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| face | Yes | ||
| width | Yes | ||
| bottom | Yes | ||
| comp_a | Yes | ||
| comp_b | Yes | ||
| height | Yes | ||
| offset | No | ||
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It describes the addition operation and explains that specifications are relative to the first compartment's floor, which is helpful. However, it lacks explicit statements about side effects (e.g., overwriting existing vents with the same id, validation of compartment overlap) or potential errors.
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 well-structured with a purpose sentence, usage note, parameter list, and return type. It is front-loaded with key information. However, the parameter descriptions are somewhat verbose, and some details (like 'Default units: m') could be integrated into the schema or shortened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no annotations, and a simple output schema (string), the description covers purpose, parameters, and return value adequately. It mentions the elevation overlap requirement and the 'OUTSIDE' option. Missing context includes potential error conditions, validation behavior, or interaction with other model elements, but overall it is sufficient for an experienced user.
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 input schema has 0% description coverage (only titles). The description compensates fully by providing detailed explanations for each parameter, including units (m), defaults (offset=0 m), allowed values (face choices), and the special value 'OUTSIDE' for comp_b. This adds critical meaning 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 clearly states the tool adds a wall vent (door, window, or opening) between two compartments. It explicitly distinguishes the resource type from sibling tools like add_mechanical_vent and add_ceiling_floor_vent by focusing on physical openings that connect compartments overlapping in elevation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that both compartments must already exist and that comp_b can be 'OUTSIDE' for an exterior vent. It provides context for when to use (connecting overlapping compartments) but does not explicitly compare to alternative vent types or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new CFAST model with its first compartment and register it.
A CFAST model must contain at least one compartment, so creation includes the first one. Add materials, further compartments, wall vents and fires with the add_* tools, then use inspect_model and run_model.
title : str Title of the simulation. May consist of letters, numbers, and/or symbols and may be up to 50 characters. room_id : str Unique alphanumeric name of the first compartment, referenced later by fires and wall vents. room_width : float Width of the compartment as measured on the X axis from its origin. Default units: m. room_depth : float Depth of the compartment as measured on the Y axis from its origin. Default units: m. room_height : float Height of the compartment as measured on the Z axis from its origin. Default units: m. time_simulation : int, optional Length of time over which the simulation takes place. Default units: s, default value: 900 s. interior_temperature : float, optional Initial ambient temperature inside the structure. Default units: °C, default value: 20 °C. exterior_temperature : float, optional Initial ambient temperature outside the structure. Default units: °C, default value: 20 °C. relative_humidity : float, optional Initial relative humidity, only specified for the interior. Default units: % RH, default value: 50 %.
str The new model_id, the model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| room_id | Yes | ||
| room_depth | Yes | ||
| room_width | Yes | ||
| room_height | Yes | ||
| time_simulation | No | ||
| relative_humidity | No | ||
| exterior_temperature | No | ||
| interior_temperature | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that the tool creates and registers the model, includes the first compartment, and returns model_id, summary, and warnings. It does not mention permissions or side effects, but for a creation tool, this is adequate transparency.
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 efficiently structured with a brief introductory paragraph, a clean parameter list with units and defaults, and a return value section. Every sentence adds value, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9 parameters (5 required) and no annotations or output schema description, the description fully covers the workflow, parameter details, and return type. It explains the creation process and next steps, making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides detailed semantics for each parameter: title constraints (max 50 chars, letters/numbers/symbols), room_id uniqueness, default units for dimensions (m), default values for optional parameters (time_simulation: 900 s, etc.). This adds substantial meaning 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 clearly states the tool creates a new CFAST model with its first compartment and registers it, using the specific verb 'Create' and resource 'CFAST model'. It distinguishes from sibling tools by mentioning the workflow of using add_* tools for further elements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that creation includes the first compartment because a model must contain at least one, and advises to use add_* tools for additional elements, then inspect_model and run_model. It provides clear context for usage but could explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the on-disk files for a model and their directory.
Use this to locate the input (.in), output (.csv) and log
files so you can open them yourself. Files appear once the model is
saved or run (run_model, or inspect_model with show_input_file=True);
before then the directory is empty.
model_id : str Id of the model whose files to locate.
str The working directory and the names of the files belonging to the model.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool is a read-only listing operation and clarifies that the directory is empty before the model is saved or run. With no annotations provided, the description carries the full burden and adds meaningful context about expected behavior.
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 front-loaded with the main purpose, then provides usage guidance, parameter details, and return value in a clear structure. While slightly verbose, every sentence adds value and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter and an output schema present, the description covers the key aspects: what it does, when to use, what files to expect, and the return format. It is complete enough for an agent to correctly invoke the 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?
The only parameter 'model_id' is described in the tool description as 'Id of the model whose files to locate', adding semantic meaning beyond the input schema which only has a title. This helps an agent understand the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'List' and resource 'on-disk files for a model', clearly distinguishing from siblings like 'get_results' and 'inspect_model' which deal with simulation data rather than file locations.
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?
Provides explicit guidance on when to use: to locate input, output, and log files for opening. Also explains timing (files appear after save or run), offering context for usage. Does not explicitly state when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read stored run results for a model (bounded; never a full dump).
Call run_model first. Without a column, returns a small preview (shape, columns, first rows) of the key. With a column, returns min / max / final value and time of max for that column — for example an upper-layer temperature column such as "ULT_1" in the "compartments" output.
model_id : str Id of the model whose results to read. key : str Output set, one of: compartments, devices, masses, vents, walls, zone, diagnostics. column : str or None, optional Column name within the key. If None, a bounded preview of the key is returned instead.
str Either a bounded preview of the key or single-column statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| column | No | ||
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the bounded nature ('never a full dump') and describes the return format for both cases. It does not cover auth, rate limits, or side effects, but the key behavioral trait (boundedness) is addressed.
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 well-structured with sections for behavior, dependencies, parameters, and returns. Every sentence adds value; no fluff. It is front-loaded with the main purpose and bounded nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (3 params with conditional logic) and presence of an output schema (not shown but noted), the description covers prerequisites, parameter details, and return types completely. No gaps or ambiguities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter: model_id, key (with enumerated valid values), and column (with conditional behavior and an example). This adds significant meaning beyond the bare 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 clearly states 'Read stored run results for a model' and specifies the bounded nature, distinguishing it from sibling tools that modify or inspect models. The verb 'Read' and resource 'run results' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly requires calling run_model first and explains when to use the optional column parameter versus omitting it. It does not explicitly state when not to use the tool or mention alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a model summary, and optionally the CFAST input file.
model_id : str
Id of the model to inspect.
show_input_file : bool, optional
If True, save the model and return the contents of the generated
CFAST input (.in) file after the summary. Default
value: False.
str The model summary, optionally followed by the input file.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | ||
| show_input_file | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the output (summary string, optionally input file contents) and hints at side effects ('save the model' for show_input_file). However, it does not explicitly state that the tool is read-only or what happens if the model_id is invalid. With no annotations, the description bears full burden; it partially met it.
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 efficiently structured like a docstring with a clear summary line, parameter listing, and return type. Every sentence is necessary, and the format is front-loaded and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, no annotations, output type str), the description covers the key aspects: what it returns and the parameters. It lacks explicit error conditions or prerequisite model existence, but for this complexity level it is nearly 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 0%, but the tool description fully explains both parameters: model_id as the id, show_input_file as an optional boolean with default false and behavior. This adds value beyond the schema titles. Minor confusion around 'save the model' could be clarified, but overall strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return a model summary, and optionally the CFAST input file.' The verb 'return' and the resource 'model summary' are specific, and the distinct purpose is evident among sibling tools that focus on creation, modification, or result retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when or why to use this tool over alternatives. The description does not mention context such as 'after creating a model' or 'instead of get_results', leaving the agent to infer usage without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the CFAST simulation for a model and summarize the outputs.
Requires the CFAST executable, resolved via the CFAST environment
variable or cfast on the PATH. Results are stored in the registry
so get_results can read them without re-running.
model_id : str Id of the model to run. timeout : int, optional Maximum CFAST run time. Default units: s, default value: 120 s.
str A bounded summary of the produced output sets.
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that results are stored in the registry and returned as a bounded summary, but does not specify mutation side effects, re-run safety, or error behavior. With no annotations, more detail would be beneficial.
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?
Well-structured with sections, no unnecessary words. Each sentence adds value: purpose, prerequisites, side effect, and return type are concisely stated.
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?
Covers prerequisites, side effects, and return type for a simulation run tool. However, lacks details on error handling and validation of model existence. Given the complexity, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. For model_id, it only repeats 'Id of the model to run.' For timeout, it adds default unit and value. This provides minimal added meaning 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 clearly states 'Run the CFAST simulation for a model and summarize the outputs.' This provides a specific verb, resource, and outcome, effectively distinguishing it from sibling tools like get_results or create_model.
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?
Describes prerequisites (CFAST executable) and post-conditions (results stored for get_results), giving context for when to run. However, lacks explicit exclusions or comparisons to alternatives beyond mentioning get_results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing ceiling/floor vent.
Selects the vent by vent_id and changes only the parameters you provide; any left as None is unchanged. The vent's id is the selector and is not changed here.
model_id : str Id of the model to modify. vent_id : str Id of the ceiling/floor vent to update. comp_top : str or None, optional Top compartment id, where the vent is in the floor. To change the connection, provide both comp_top and comp_bottom. None leaves the connection unchanged. comp_bottom : str or None, optional Bottom compartment id, or "OUTSIDE". To change the connection, provide both comp_top and comp_bottom. None leaves the connection unchanged. area : float or None, optional Cross-sectional area of the vent opening. Default units: m². None leaves it unchanged. type : str or None, optional Type of ceiling/floor vent: FLOOR or CEILING. None leaves it unchanged. shape : str or None, optional Shape factor: ROUND or SQUARE. None leaves it unchanged. offsets : list[float] or None, optional For visualization only, [x_offset, y_offset]. Default units: m. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| type | No | ||
| shape | No | ||
| offsets | No | ||
| vent_id | Yes | ||
| comp_top | No | ||
| model_id | Yes | ||
| comp_bottom | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes partial update (only provided params changed), returns confirmation string. No annotations to contradict. Lacks auth/rate limit info but sufficient for a simple update tool.
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?
Well-organized with intro, parameter list, returns. Each sentence is informative and concise. No fluff.
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?
Covers behavior, all 8 parameters, and return value. No gaps given complexity. Output schema existing but description still explains return type.
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?
Detailed parameter descriptions with constraints (e.g., for connection: need both comp_top and comp_bottom), types, units, and default behavior (None leaves unchanged). Compensates for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear statement: 'Update an existing ceiling/floor vent.' Differentiates from add_ceiling_floor_vent sibling. Specific verb and resource, with explanation of selective update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to select by vent_id and only changed parameters are updated. Implies use when modifying existing vent, not adding. No explicit alternatives but context is clear among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update parameters of an existing compartment.
Selects the compartment by comp_id and changes only the parameters you provide; any left as None is unchanged. Use this to attach surface materials to the first compartment (created bare by create_model) or to revise any compartment later. Any surface material id given must already exist in the model — add it first with add_material. The compartment's id itself is the selector and is not changed here.
model_id : str Id of the model to modify. comp_id : str Id of the compartment to update. width : float or None, optional New width of the compartment as measured on the X axis from its origin. Default units: m. None leaves it unchanged. depth : float or None, optional New depth of the compartment as measured on the Y axis from its origin. Default units: m. None leaves it unchanged. height : float or None, optional New height of the compartment as measured on the Z axis from its origin. Default units: m. None leaves it unchanged. ceiling_mat_id : str or None, optional Material id defining the ceiling surface. None leaves it unchanged. ceiling_thickness : float or None, optional Thickness of the ceiling surface. Default units: m. None leaves it unchanged. wall_mat_id : str or None, optional Material id defining the wall surfaces. None leaves it unchanged. wall_thickness : float or None, optional Thickness of the wall surfaces. Default units: m. None leaves it unchanged. floor_mat_id : str or None, optional Material id defining the floor surface. None leaves it unchanged. floor_thickness : float or None, optional Thickness of the floor surface. Default units: m. None leaves it unchanged. origin_x : float or None, optional Absolute x coordinate of the lower, left, front corner of the room. Negative values are not allowed. Default units: m. None leaves it unchanged. origin_y : float or None, optional Absolute y coordinate of the lower, left, front corner of the room. Negative values are not allowed. Default units: m. None leaves it unchanged. origin_z : float or None, optional Height of the floor of the compartment with respect to the station elevation. Default units: m. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | ||
| width | No | ||
| height | No | ||
| comp_id | Yes | ||
| model_id | Yes | ||
| origin_x | No | ||
| origin_y | No | ||
| origin_z | No | ||
| wall_mat_id | No | ||
| floor_mat_id | No | ||
| ceiling_mat_id | No | ||
| wall_thickness | No | ||
| floor_thickness | No | ||
| ceiling_thickness | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It explains partial update behavior, constraints (negative origins not allowed, units in meters), and return type (string with confirmation and warnings). Lacks mention of side effects like model rebuild, but is otherwise transparent.
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?
Structured with a summary paragraph followed by parameter list. Front-loaded with purpose. While the parameter list is long, it is necessary given the schema coverage. Could slightly reduce redundancy but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, 2 required, and existence of output schema, the description covers selection logic, update behavior, constraints, parameter details, and return value. Leaves no critical gaps.
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 has 0% description coverage, so description compensates fully. Details each parameter: width, depth, height, origins, material ids, thicknesses, with units, default (None leaves unchanged), and constraints (e.g., no negative origin_x/y).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update parameters of an existing compartment.' and explains that selection is by comp_id with partial update. It distinguishes from 'add_compartment' and other update tools, making the purpose unambiguous.
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?
Provides context: use to attach surface materials to first compartment created bare by create_model, or revise any compartment. Warns that material ids must exist (use add_material). No explicit when-not-to-use, but sufficient guidance for the main use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing device (target or detector).
Selects the device by device_id and changes only the parameters you provide; any left as None is unchanged. The device's id is the selector and is not changed here.
model_id : str Id of the model to modify. device_id : str Id of the device to update. comp_id : str or None, optional Compartment in which the device is located. None leaves it unchanged. location : list[float] or None, optional Position [x, y, z] from the left wall, front wall and floor. Default units: m. None leaves it unchanged. type : str or None, optional One of PLATE, CYLINDER, HEAT_DETECTOR, SMOKE_DETECTOR, SPRINKLER. None leaves it unchanged. material_id : str or None, optional What the target is made of; must already exist. None leaves it unchanged. surface_orientation : str or None, optional Predefined surface orientation for targets. None leaves it unchanged. normal : list[float] or None, optional Unit vector [nx, ny, nz] perpendicular to the target surface. None leaves it unchanged. thickness : float or None, optional Thickness of the target material. Default units: m. None leaves it unchanged. temperature_depth : float or None, optional Depth at which the internal target temperature is reported (meters when depth_units="M", else a fraction in [0, 1]). None leaves it unchanged. depth_units : str or None, optional Units for temperature_depth: "M" for meters. None leaves it unchanged. setpoint : float or None, optional Activation temperature for HEAT_DETECTOR and SPRINKLER. Default units: °C. None leaves it unchanged. rti : float or None, optional Response Time Index. Default units: (m·s)^(1/2). None leaves it unchanged. obscuration : float or None, optional Obscuration at or above which a SMOKE_DETECTOR activates. Default units: %/m. None leaves it unchanged. spray_density : float or None, optional Amount of water dispersed by a sprinkler. Default units: m/s. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| rti | No | ||
| type | No | ||
| normal | No | ||
| comp_id | No | ||
| location | No | ||
| model_id | Yes | ||
| setpoint | No | ||
| device_id | Yes | ||
| thickness | No | ||
| depth_units | No | ||
| material_id | No | ||
| obscuration | No | ||
| spray_density | No | ||
| temperature_depth | No | ||
| surface_orientation | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavior. It explains partial update semantics ('changes only the parameters you provide; any left as None is unchanged') and notes that device_id is unchanged. No mention of error conditions or permissions, but basic behavioral traits are covered.
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 appropriately long for a parameter-heavy tool. It starts with a concise behavioral summary, then a structured Parameters section. No redundant information, though some units could be standardized in a separate note.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (15 params, no annotations, output schema exists), the description is quite complete. It covers update behavior, parameter explanations, and return type. Could mention that some parameters are device-type-specific, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full burden. It provides detailed explanations for each of the 15 parameters, including units, constraints, and applicability (e.g., activation temperature for detectors). This greatly exceeds the schema which only has type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing device (target or detector).' with a specific verb and resource. It distinguishes from siblings like add_device by focusing on updating an existing device.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains that only provided parameters are changed and that device_id is the selector. It gives clear context for use but does not explicitly mention when not to use (e.g., to add a device use add_device).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing fire.
Selects the fire by its instance id and changes only the parameters you provide; any left as None is unchanged. The fire instance id is the selector and is not changed here. Changing comp_id moves the fire to another compartment, which must already exist.
model_id : str Id of the model to modify. id : str Id of the fire instance to update. comp_id : str or None, optional Name of the compartment where the fire occurs. None leaves it unchanged. fire_id : str or None, optional Name of the fire definition (fuel composition and HRR curve). None leaves it unchanged. location : list[float] or None, optional Position [x, y] of the center of the base of the fire relative to the front left corner of the compartment. Default units: m. None leaves it unchanged. data_table : list[list[float]] or None, optional Time-dependent fire properties: one row per time point, with columns [TIME (s), HRR (kW), HEIGHT (m), AREA (m²), CO_YIELD, SOOT_YIELD, HCN_YIELD, HCL_YIELD, TRACE_YIELD], yields in kg/kg. None leaves it unchanged. carbon : float or None, optional Number of carbon atoms in the fuel molecule. None leaves it unchanged. chlorine : float or None, optional Number of chlorine atoms in the fuel molecule; assumed to completely react to form HCl. None leaves it unchanged. hydrogen : float or None, optional Number of hydrogen atoms in the fuel molecule. None leaves it unchanged. nitrogen : float or None, optional Number of nitrogen atoms in the fuel molecule; assumed to completely react to form HCN. None leaves it unchanged. oxygen : float or None, optional Number of oxygen atoms in the fuel molecule. None leaves it unchanged. heat_of_combustion : float or None, optional The energy released per unit mass of fuel consumed. Default units: kJ/kg. None leaves it unchanged. radiative_fraction : float or None, optional The fraction of the combustion energy that is emitted in the form of thermal radiation. Default units: none. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings (for example a fire located outside the compartment footprint).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| carbon | No | ||
| oxygen | No | ||
| comp_id | No | ||
| fire_id | No | ||
| chlorine | No | ||
| hydrogen | No | ||
| location | No | ||
| model_id | Yes | ||
| nitrogen | No | ||
| data_table | No | ||
| heat_of_combustion | No | ||
| radiative_fraction | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains the partial-update behavior (only provided parameters change), the effect of changing comp_id (moves fire, compartment must exist), and the return value (confirmation, summary, warnings). Side effects and safety are partially covered, but could be more explicit about error conditions.
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 well-structured with a summary, parameter list, and returns section. It is front-loaded with the core logic. While somewhat lengthy due to the parameter details, every sentence adds necessary information, making it appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, no annotations, and an output schema (mentioned but not shown), the description provides comprehensive information: parameter semantics, selection logic, update behavior, and return value with warnings. It leaves no major gaps for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by providing detailed explanations for all 13 parameters, including units, optionality, and the meaning of leaving a parameter unchanged (None). This adds significant value beyond the bare 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 clearly states 'Update an existing fire' and explains the selection by instance id and partial-update semantics. It distinguishes from add_fire (create) by focusing on update, and from other update_* tools by specifying the resource (fire).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly says when to use the tool (when updating an existing fire) but does not explicitly state when not to use it or mention alternative tools. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update thermophysical properties of an existing material.
Selects the material by material_id and changes only the parameters you provide; any left as None is unchanged. The material's id is the selector and is not changed here.
model_id : str Id of the model to modify. material_id : str Id of the material to update. conductivity : float or None, optional Thermal conductivity for the material. Default units: W/(m·K). None leaves it unchanged. density : float or None, optional Density for the material. Default units: kg/m³. None leaves it unchanged. specific_heat : float or None, optional Specific heat for the material. Default units: kJ/(kg·K). None leaves it unchanged. thickness : float or None, optional Thickness of the material. Default units: m. None leaves it unchanged. emissivity : float or None, optional Emissivity of the material surface; the fraction of radiation that is absorbed by the material. Default units: none. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| density | No | ||
| model_id | Yes | ||
| thickness | No | ||
| emissivity | No | ||
| material_id | Yes | ||
| conductivity | No | ||
| specific_heat | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that only provided parameters are changed (others remain unchanged) and that material_id is the selector and not modifiable. However, it does not mention permissions, side effects, or whether the update is irreversible. This is adequate but leaves some gaps.
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 well-structured: a concise summary followed by a parameter list and return specification. Every section adds value. While a bit lengthy, it is appropriately sized for the tool's complexity and avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, parameter semantics, and return value. It explains the partial update behavior. Missing are error conditions (e.g., if material_id doesn't exist) and prerequisites. Overall, it is largely complete for a tool with 7 parameters and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema_description_coverage is 0%, so the description compensates fully. It documents each parameter with units, default behavior (None leaves unchanged), and clarifications (e.g., emissivity is a fraction). This adds significant value beyond the schema, which lacks parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update thermophysical properties of an existing material', using a specific verb ('update') and resource ('material'). It distinguishes itself from sibling tools like 'add_material' (create) and other update tools (e.g., 'update_compartment') by focusing on material properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used to modify properties of an existing material, as opposed to creating one (use 'add_material'). It does not explicitly state alternatives or when not to use it, but the context of sibling names makes the usage fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing mechanical vent.
Selects the vent by vent_id and changes only the parameters you provide; any left as None is unchanged. The vent's id is the selector and is not changed here.
model_id : str Id of the model to modify. vent_id : str Id of the mechanical vent to update. comp_from : str or None, optional Compartment from which the fan flow originates, or "OUTSIDE". To change the connection, provide both comp_from and comp_to. None leaves the connection unchanged. comp_to : str or None, optional Compartment to which the fan flow terminates, or "OUTSIDE". To change the connection, provide both comp_from and comp_to. None leaves the connection unchanged. flow : float or None, optional Constant volumetric flow rate of the fan. Default units: m³/s. None leaves it unchanged. area : list[float] or None, optional Cross-sectional area of the opening for each connection [area_from, area_to]. Default units: m². None leaves it unchanged. heights : list[float] or None, optional Height of the midpoint of the duct opening above the floor for each connection [height_from, height_to]. Default units: m. None leaves it unchanged. orientations : list[str] or None, optional Flow orientation for each connection, HORIZONTAL or VERTICAL. None leaves it unchanged. cutoffs : list[float] or None, optional Pressure control values [begin_drop_off_pressure, zero_flow_pressure]. Default units: Pa. None leaves it unchanged. offsets : list[float] or None, optional For visualization only, [x_offset, y_offset]. Default units: m. None leaves it unchanged. filter_time : float or None, optional Time at which mechanical vent filtering begins. Default units: s. None leaves it unchanged. filter_efficiency : float or None, optional Portion of soot and trace species mass removed (0-100 %). None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| flow | No | ||
| comp_to | No | ||
| cutoffs | No | ||
| heights | No | ||
| offsets | No | ||
| vent_id | Yes | ||
| model_id | Yes | ||
| comp_from | No | ||
| filter_time | No | ||
| orientations | No | ||
| filter_efficiency | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description details parameter behavior (None leaves unchanged, connection requires both comp_from and comp_to) and return value (confirmation, summary, warnings). It lacks information on side effects or atomicity but covers core behavioral traits.
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 well-structured with an intro, parameter list, and returns section. It is fairly concise for 12 parameters, though some grouping could reduce repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, 2 required, and an output schema, the description covers all parameters with usage context and return type. Minor gaps like validation constraints do not significantly impair completeness.
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 0%, so the description provides comprehensive parameter semantics: type, meaning, default units, and usage notes (e.g., 'None leaves it unchanged', 'To change the connection, provide both'). This adds essential value 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 states the tool updates an existing mechanical vent, selects by vent_id, and only changes provided parameters. This is a specific verb+resource that clearly distinguishes it from sibling tools like add_mechanical_vent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use the tool (updating existing vents) and implies creation is done via add_mechanical_vent. However, it does not explicitly state when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the simulation environment (scenario and ambient conditions).
A model has a single simulation environment, set at create_model; this changes only the parameters you provide; any left as None is unchanged.
model_id : str Id of the model to modify. title : str or None, optional Title of the simulation. May consist of letters, numbers, and/or symbols and may be up to 50 characters. None leaves it unchanged. time_simulation : int or None, optional Length of time over which the simulation takes place. Default units: s. None leaves it unchanged. interior_temperature : float or None, optional Initial ambient temperature inside the structure. Default units: °C. None leaves it unchanged. exterior_temperature : float or None, optional Initial ambient temperature outside the structure. Default units: °C. None leaves it unchanged. relative_humidity : float or None, optional Initial relative humidity, only specified for the interior. Default units: % RH. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| model_id | Yes | ||
| time_simulation | No | ||
| relative_humidity | No | ||
| exterior_temperature | No | ||
| interior_temperature | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It explains the None-leave-unchanged behavior and return value (confirmation, summary, warnings), but lacks details on side effects, atomicity, or prerequisites (e.g., model state). Adequate but not thorough.
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?
Structured as a summary sentence followed by parameter list with clear formatting. Somewhat verbose with redundant 'None leaves it unchanged' phrasing, but overall well-organized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no annotations, and presence of output schema, description covers parameter details well and mentions the context of a single simulation environment. Lacks behavioral constraints or error conditions, but output schema mitigates need to describe return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description compensates with detailed parameter meanings: title character/length limits, units for time and temperatures, and scope of relative humidity. Adds significant value beyond schema types.
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?
Description clearly states 'Update the simulation environment (scenario and ambient conditions)' and differentiates from sibling tools by noting that a model has a single simulation environment set at create_model, making this tool unique for modifying it.
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 advises that only provided parameters are changed and None leaves them unchanged, guiding proper usage. However, it does not explicitly state when not to use this tool versus alternatives like update_compartment or update_device, though the context of simulation environment vs. compartments is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing surface connection.
Surface connections have no id, so they are selected by index (their 0-based position in the order they were added). Only the parameters you provide change; any left as None is unchanged.
model_id : str Id of the model to modify. index : int 0-based position of the surface connection to update. conn_type : str or None, optional Type of connection: WALL or FLOOR. None leaves it unchanged. comp_id : str or None, optional First compartment id. None leaves it unchanged. comp_ids : str or None, optional Second compartment id. None leaves it unchanged. fraction : float or None, optional Fraction (0-1) of connected vertical surface area, for WALL connections. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | ||
| comp_id | No | ||
| comp_ids | No | ||
| fraction | No | ||
| model_id | Yes | ||
| conn_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Comprehensively discloses behavior: no id, index-based selection, only provided parameters change (others unchanged), and return value description. No annotations provided, so description carries full burden and does so effectively.
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?
Well-structured with introductory paragraph and clear parameter list. Slightly verbose with None repetition, but overall efficient and front-loaded with key info.
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?
Fully explains all parameters, selection mechanism, and return value. Given no output schema (but annotation says it exists), the description covers what the agent needs to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description includes a full parameter list with explanations for each, adding significant meaning beyond the bare schema definitions.
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?
Clearly states 'Update an existing surface connection' and explains the index-based selection due to lack of id, distinguishing it from sibling update tools that use ids.
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?
Provides clear context on how surface connections are selected by index and which parameters change. Could be improved by explicitly stating when not to use (e.g., if id available), but the use case is straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing wall vent.
Selects the vent by vent_id and changes only the parameters you provide; any left as None is unchanged. The vent's id is the selector and is not changed here.
model_id : str Id of the model to modify. vent_id : str Id of the wall vent to update. comp_a : str or None, optional First compartment id; the reference for all vent specifications. To change the connection, provide both comp_a and comp_b. None leaves the connection unchanged. comp_b : str or None, optional Second compartment id, or "OUTSIDE" for the exterior. To change the connection, provide both comp_a and comp_b. None leaves the connection unchanged. bottom : float or None, optional Position of the bottom of the opening relative to the floor of the first compartment. Default units: m. None leaves it unchanged. height : float or None, optional Height of the opening relative to the bottom of the opening. Default units: m. None leaves it unchanged. width : float or None, optional Width of the opening. Default units: m. None leaves it unchanged. face : str or None, optional The wall on which the vent is positioned: FRONT, REAR, LEFT or RIGHT. None leaves it unchanged. offset : float or None, optional For visualization only, the horizontal distance between the near edge of the vent and the origin of the axis defined by the selected face. Default units: m. None leaves it unchanged.
str Confirmation, the updated model summary, and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| face | No | ||
| width | No | ||
| bottom | No | ||
| comp_a | No | ||
| comp_b | No | ||
| height | No | ||
| offset | No | ||
| vent_id | Yes | ||
| model_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool performs partial updates, the vent_id is unchanged, and returns confirmation and warnings. It lacks details on side effects, permissions, or reversibility, but is adequate.
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 well-structured with a brief overview, parameter list, and return value. It is concise, front-loaded, and every sentence is informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no annotations, and an output schema mentioned, the description covers purpose, behavior, parameter details, and return format completely. There are no obvious gaps for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides detailed semantics for each parameter: purpose, behavior on None, and constraints (e.g., both comp_a and comp_b needed for connection change). This adds significant value 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 uses a specific verb 'Update' and resource 'wall vent', clearly indicating the action. It differentiates from sibling tools like 'add_wall_vent' by focusing on modification. The mention of selecting by vent_id and partial update adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states to use when updating an existing vent, with partial updates by leaving parameters as None. It implies not to use for creation (add_wall_vent) but lacks explicit alternatives or when-not-to-use statements.
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.
v0.1.0add_ceiling_floor_ventadd_compartmentadd_deviceadd_fireadd_materialadd_mechanical_ventadd_surface_connectionadd_wall_ventcreate_modelget_model_filesget_resultsinspect_modelrun_modelupdate_ceiling_floor_ventupdate_compartmentupdate_deviceupdate_fireupdate_materialupdate_mechanical_ventupdate_simulationupdate_surface_connectionupdate_wall_ventScored across 22 tools
Each tool targets a distinct entity (compartment, vent type, fire, material, device, simulation parameters, etc.) with clear descriptions. The three vent types are differentiated by their mechanics (wall, ceiling/floor, mechanical) and purposes.
All tools follow a consistent verb_noun pattern using snake_case. Add/update pairs are uniform, and lifecycle tools like create_model, inspect_model, run_model maintain the pattern without mixing conventions.
22 tools cover the full range of operations for creating, configuring, and running CFAST fire simulations. The count is well-scoped for the domain's complexity without being excessive or insufficient.
The tool surface includes create, read (via inspect/get_results), and update operations for all major components, but notably lacks delete/remove tools for compartments, vents, fires, etc. This is a significant gap for model management.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Design, solve and simulate HVAC systems from real components, weather years and buildings.
Conversational what-if simulation: build, diagnose and compare Petri-net models; CC0 catalog.
