Skip to content

Scripting coverage: what a script does of each tool ​

The script API is the product. The MutinyBIM tool server lists 10 tools by default: five script tools (bim_script_reference, bim_check_output, bim_run_script, bim_apply_output, bim_save_part_type), four reads (bim_model_summary, bim_query_elements, bim_inspect_network, bim_validation_issues) and bim_enable_pack. Everything else is done by writing a script with @permitzip/bim-script.

The other 159 tools stay on the server, off, in families an agent can turn on (--packs, /packs/<family>/mcp, or bim_enable_pack). This page says, for each of them, what a script uses instead. Every tool marked covered is a retirement candidate; retiring any of them is the maintainer's call.

How a script reaches the model: ctx.edit(command) takes any of the kernel's and the add-ons' commands (198 today; bim_script_reference({ command }) shows one's fields), the kit's helpers build the common ones with typed units, ctx.model reads the model as far as the script's reads go, ctx.calc runs the engineering calculations on it, ctx.read runs the add-ons' computed reads (panel loads, rebalance and room-template plans, duct size advice, catalogues), ctx.propose / ctx.acceptGhosts place devices by a code's spacing, and the kit's planners (documents.autoTag, autoDimension, packSheet, oneLine, scheduleRows, checks.clashes, building.surfacesAt) work on the model as the script has it so far. A script imports only @permitzip/bim-script and runs sealed: no files, network or host services.

Summary ​

CoveredPartialHost stepMissing
Before (Nov 7, start of the change)10822218
After script-first (PR #3358)11423211
Now (script API gaps closed)1380210

Covered: a script does the same job today. Partial: a script does most of it; the note says what is missing. Host step: the job needs the host app (rendering, printing, issuing, another company's cloud, reading pictures with AI, libraries the host stores), so it stays a tool or a host action by design. Missing: not in the script API yet.

FamilyToolsCoveredPartialHost stepMissing
core2719080
drafting1717000
ducts-pipes2020000
electrical1818000
plumbing55000
views-sheets1817010
coordination1610060
groups-phases1515000
parts116050
calcs88000
schedules43010
All1591380210

The core family is the catalogue's core pack less the four reads already in the default list; the scripts family is entirely in the default list.

core ​

ToolScript equivalentStatusNote
bim_schedule_readdocuments.scheduleRows(ctx, schedule): cells by column (SI), totals, row countcoveredpanel and feeder forms are add-on reads (electrical.loads); script covers it → retirement candidate (maintainer's call)
bim_list_part_typesparts.starterTypes(ctx, words) and ctx.model.partTypes()coveredthe firm library's saved types are bim_list_firm_parts, a host read; script covers it → retirement candidate (maintainer's call)
bim_list_levelsbim_query_elements kind level; ctx.model.levels() in a scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_list_views_and_sheetsbim_query_elements kind view / sheetcoveredscript covers it → retirement candidate (maintainer's call)
bim_list_linked_modelsbim_query_elements (linked references are elements)coveredscript covers it → retirement candidate (maintainer's call)
bim_surfaces_at`building.surfacesAt(ctx,{ element })`covered
bim_describe_commandsbim_script_reference({ command })coveredscript covers it → retirement candidate (maintainer's call)
bim_preview_part_editbim_run_script (every script run is a preview)coveredscript covers it → retirement candidate (maintainer's call)
bim_preview_route_editbim_run_scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_preview_views_sheets_editbim_run_scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_apply_views_sheets_editbim_apply_outputcoveredscript covers it → retirement candidate (maintainer's call)
bim_render_view_imagenonehost stepdrawing pictures needs the host's renderer
bim_render_sheet_imagenonehost stepdrawing pictures needs the host's renderer
bim_print_sheet_pdfnonehost stepprinting writes files through the host
bim_print_view_pdfnonehost stepprinting writes files through the host
bim_print_set_pdfnonehost stepprinting writes files through the host
bim_issue_setnonehost stepissuing records a set and its files in the host
bim_place_partequipment.place; ctx.edit: place_partcoveredscript covers it → retirement candidate (maintainer's call)
bim_move_elementsctx.edit: move_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_rotate_elementsctx.edit: rotate_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_copy_elementsctx.edit: copy_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_elementsctx.edit: delete_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_set_parametersctx.edit: set_parameterscoveredscript covers it → retirement candidate (maintainer's call)
bim_move_wallctx.edit: move_wallcoveredscript covers it → retirement candidate (maintainer's call)
bim_lint_configurenonehost steplint settings are stored by the host
bim_lint_checkchecks.clashes(ctx, { ruleset }) on the script's modelcoveredlinked models' elements and accepted findings are the host's; script covers it → retirement candidate (maintainer's call)
bim_status_snapshotbim_model_summary and checks.clashes for the model's parthost stepprints and issues are the host's record

drafting ​

ToolScript equivalentStatusNote
bim_list_view_annotationsbim_query_elements (drawing items of a view)coveredscript covers it → retirement candidate (maintainer's call)
bim_add_dimensiondocuments.dimension; ctx.edit: add_drawing_itemcoveredscript covers it → retirement candidate (maintainer's call)
bim_auto_dimensiondocuments.autoDimension(ctx, { view, elements, mode })coveredscript covers it → retirement candidate (maintainer's call)
bim_add_tagdocuments.tag; ctx.edit: add_drawing_itemcoveredscript covers it → retirement candidate (maintainer's call)
bim_preview_auto_tagdocuments.autoTag in bim_run_script (the run is the preview)coveredscript covers it → retirement candidate (maintainer's call)
bim_auto_tag_viewdocuments.autoTag(ctx, { view, categories })coveredsame planner: tags placed clear of each other; script covers it → retirement candidate (maintainer's call)
bim_add_notectx.edit: create_text_notecoveredscript covers it → retirement candidate (maintainer's call)
bim_edit_annotationctx.edit: update_drawing_item, delete_drawing_item, move_text_note, delete_text_notecoveredscript covers it → retirement candidate (maintainer's call)
bim_set_tag_textctx.edit: set_tag_textcoveredscript covers it → retirement candidate (maintainer's call)
bim_list_tag_stylesbim_query_elements (tag styles)coveredscript covers it → retirement candidate (maintainer's call)
bim_save_tag_stylectx.edit: create_tag_style, update_tag_style, delete_tag_stylecoveredscript covers it → retirement candidate (maintainer's call)
bim_apply_tag_stylectx.edit: update_drawing_itemcoveredscript covers it → retirement candidate (maintainer's call)
bim_list_detail_componentsdocuments.detailLibrary(ctx)coveredscript covers it → retirement candidate (maintainer's call)
bim_draw_detailctx.edit: add_drawing_itemcoveredscript covers it → retirement candidate (maintainer's call)
bim_modify_detailctx.edit: update_drawing_itemcoveredtrim, extend and fillet geometry is computed by the script itself; script covers it → retirement candidate (maintainer's call)
bim_copy_detail_itemsctx.edit: copy_drawing_itemscoveredscript covers it → retirement candidate (maintainer's call)
bim_set_detail_groupctx.edit: update_drawing_itemcoveredscript covers it → retirement candidate (maintainer's call)

ducts-pipes ​

ToolScript equivalentStatusNote
bim_route_runroutes.along, routes.branch, routes.drop; ctx.edit: route_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_connect_runsroutes.connectInto; ctx.edit: connect_runs, auto_connect_runscoveredscript covers it → retirement candidate (maintainer's call)
bim_disconnect_runctx.edit: disconnect_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_route_flexctx.edit: route_flex, route_into_flexcoveredscript covers it → retirement candidate (maintainer's call)
bim_resize_runctx.edit: resize_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_slide_branchctx.edit: slide_branchcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_terminal_airflowctx.edit: set_terminal_cfmcoveredscript covers it → retirement candidate (maintainer's call)
bim_move_equipmentctx.edit: move_equipmentcoveredscript covers it → retirement candidate (maintainer's call)
bim_resize_riserctx.edit: resize_risercoveredscript covers it → retirement candidate (maintainer's call)
bim_list_fitting_typesroutes.fittingTypes(ctx, { domain, service })coveredscript covers it → retirement candidate (maintainer's call)
bim_swap_fittingctx.edit: swap_fitting, elbow_to_teecoveredscript covers it → retirement candidate (maintainer's call)
bim_offset_runctx.edit: offset_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_change_elevationctx.edit: change_elevationcoveredscript covers it → retirement candidate (maintainer's call)
bim_split_runctx.edit: split_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_resize_stretchctx.edit: resize_stretch, stretch_to_sidecoveredscript covers it → retirement candidate (maintainer's call)
bim_drag_runctx.edit: drag_runcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_system_designctx.edit: set_system_designcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_duct_insulationctx.edit: set_run_insulationcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_sloperoutes.along with slope; ctx.edit: set_slopecoveredscript covers it → retirement candidate (maintainer's call)
bim_place_pipe_accessoryctx.edit: place_run_accessorycoveredscript covers it → retirement candidate (maintainer's call)

electrical ​

ToolScript equivalentStatusNote
bim_electrical_reportctx.read("electrical.loads", { panel }) per panel and ctx.read("electrical.check")coveredscript covers it → retirement candidate (maintainer's call)
bim_read_panelctx.read("bim_read_panel", { panel }) for slots, ctx.read("electrical.loads") for loads and phase totalscoveredscript covers it → retirement candidate (maintainer's call)
bim_electrical_catalogctx.read("electrical.catalog"), "electrical.feeder_proposal", "electrical.check"coveredname the NEC edition; script covers it → retirement candidate (maintainer's call)
bim_propose_links_from_textctx.read("bim_propose_links_from_text")coveredreads the circuit numbers typed on devices in the model; no AI; script covers it → retirement candidate (maintainer's call)
bim_preview_circuit_editbim_run_scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_create_circuitctx.edit: create_service_link, add_link_memberscoveredscript covers it → retirement candidate (maintainer's call)
bim_edit_circuitctx.edit: edit_service_linkcoveredscript covers it → retirement candidate (maintainer's call)
bim_add_to_circuitctx.edit: add_link_memberscoveredscript covers it → retirement candidate (maintainer's call)
bim_remove_from_circuitctx.edit: remove_link_memberscoveredscript covers it → retirement candidate (maintainer's call)
bim_feed_panelctx.edit: create_service_link, edit_service_linkcoveredscript covers it → retirement candidate (maintainer's call)
bim_rebalance_panelctx.read("electrical.rebalance_plan", { panel }), then ctx.editSteps(plan.command)coveredscript covers it → retirement candidate (maintainer's call)
bim_save_electrical_typectx.edit: save_catalog_entrycoveredscript covers it → retirement candidate (maintainer's call)
bim_apply_circuit_templatectx.read("electrical.circuit_template_plan", { template, units }), then ctx.editSteps(plan.command)coveredthe script names each unit's panel; script covers it → retirement candidate (maintainer's call)
bim_preview_one_linedocuments.oneLine in bim_run_script (the run is the preview)coveredscript covers it → retirement candidate (maintainer's call)
bim_layout_one_line`documents.oneLine(ctx,{ name, live })`covered
bim_propose_receptaclesctx.propose("electrical.receptacles", { typeId, roomIds, options }), then ctx.acceptGhostscoveredNEC 210.52 spacing or a density preset; name the edition; script covers it → retirement candidate (maintainer's call)
bim_accept_receptaclesctx.edit: place_devicescoveredscript covers it → retirement candidate (maintainer's call)
bim_place_service_layoutctx.edit: place_service_layoutcoveredscript covers it → retirement candidate (maintainer's call)

plumbing ​

ToolScript equivalentStatusNote
bim_place_load_pointsctx.edit: create_load_pointcoveredscript covers it → retirement candidate (maintainer's call)
bim_edit_load_pointctx.edit: edit_load_point, delete_load_pointscoveredscript covers it → retirement candidate (maintainer's call)
bim_save_connection_typectx.edit: save_connection_typecoveredscript covers it → retirement candidate (maintainer's call)
bim_plumbing_catalogctx.read("bim_plumbing_catalog")coveredscript covers it → retirement candidate (maintainer's call)
bim_plumbing_designctx.edit: set_system_design, set_project_parameterscoveredscript covers it → retirement candidate (maintainer's call)

views-sheets ​

ToolScript equivalentStatusNote
bim_create_viewdocuments.planView, documents.ceilingView; ctx.edit: create_viewcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_view_propertiesctx.edit: set_view_properties, set_view_cropcoveredscript covers it → retirement candidate (maintainer's call)
bim_rename_viewctx.edit: rename_viewcoveredscript covers it → retirement candidate (maintainer's call)
bim_duplicate_viewdocuments.duplicateView; ctx.edit: duplicate_viewcoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_viewctx.edit: delete_viewcoveredscript covers it → retirement candidate (maintainer's call)
bim_create_sheetdocuments.sheet; ctx.edit: create_sheetcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_sheet_propertiesdocuments.setSheet; ctx.edit: set_sheet_propertiescoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_sheetctx.edit: delete_sheetcoveredscript covers it → retirement candidate (maintainer's call)
bim_place_viewportdocuments.place; ctx.edit: place_viewportcoveredscript covers it → retirement candidate (maintainer's call)
bim_edit_viewportctx.edit: move_viewport, resize_viewport, set_viewport_scale, set_viewport_north_arrow, remove_viewportcoveredscript covers it → retirement candidate (maintainer's call)
bim_preview_sheet_layoutdocuments.packSheet in bim_run_script (the run is the preview)coveredscript covers it → retirement candidate (maintainer's call)
bim_auto_layout_sheetdocuments.packSheet(ctx, sheet, { mode, fitScales })coveredscript covers it → retirement candidate (maintainer's call)
bim_set_issue_statusnonehost stepissue status is recorded by the host's issuing
bim_add_sheet_notectx.edit: create_text_notecoveredscript covers it → retirement candidate (maintainer's call)
bim_edit_text_notectx.edit: edit_text_note, resize_text_notecoveredscript covers it → retirement candidate (maintainer's call)
bim_create_3d_viewctx.edit: create_3d_viewcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_3d_view_cameractx.edit: set_3d_view_cameracoveredscript covers it → retirement candidate (maintainer's call)
bim_set_3d_crop_boxctx.edit: set_3d_crop_boxcoveredscript covers it → retirement candidate (maintainer's call)

coordination ​

ToolScript equivalentStatusNote
bim_browse_autodesk_docsnonehost stepreads another company's cloud through the host's connection
bim_link_from_autodesk_docsnonehost steplinks an outside model through the host's connection
bim_update_linked_modelnonehost stepfetches a new version through the host's connection
bim_unlink_linked_modelnonehost stepthe host keeps the link records
bim_sync_linked_levelsbuilding.levelSyncPlan and building.syncLevelscoveredthe linked model's storeys come from the host's link; a script takes them as values; script covers it → retirement candidate (maintainer's call)
bim_update_levelctx.edit: update_levelcoveredscript covers it → retirement candidate (maintainer's call)
bim_create_levelbuilding.level; ctx.edit: create_levelcoveredscript covers it → retirement candidate (maintainer's call)
bim_read_coordinatesbim_model_summary / bim_query_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_preview_coordinates_editbim_run_scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_project_originctx.edit: set_project_origincoveredscript covers it → retirement candidate (maintainer's call)
bim_set_survey_pointctx.edit: set_survey_pointcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_true_northctx.edit: set_true_northcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_working_anglectx.edit: set_working_anglecoveredscript covers it → retirement candidate (maintainer's call)
bim_lint_accept_findingnonehost stepaccepted findings are stored by the host
bim_lint_retract_acceptancenonehost stepaccepted findings are stored by the host
bim_trace_roomsbuilding.spaceInWalls; ctx.edit: place_space_in_wallscoveredscript covers it → retirement candidate (maintainer's call)

groups-phases ​

ToolScript equivalentStatusNote
bim_list_groups_and_phasesbim_query_elements (groups, phases)coveredscript covers it → retirement candidate (maintainer's call)
bim_preview_organization_editbim_run_scriptcoveredscript covers it → retirement candidate (maintainer's call)
bim_create_groupctx.edit: create_groupcoveredscript covers it → retirement candidate (maintainer's call)
bim_update_groupctx.edit: update_group, lock_group, set_group_typicalcoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_groupctx.edit: delete_groupcoveredscript covers it → retirement candidate (maintainer's call)
bim_assign_to_groupctx.edit: assign_elements_to_groupcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_active_group_and_phasectx.edit: set_active_group, set_active_phasecoveredscript covers it → retirement candidate (maintainer's call)
bim_create_phasectx.edit: create_phasecoveredscript covers it → retirement candidate (maintainer's call)
bim_update_phasectx.edit: update_phasecoveredscript covers it → retirement candidate (maintainer's call)
bim_set_element_phasesctx.edit: set_element_phases, demolish_elementscoveredscript covers it → retirement candidate (maintainer's call)
bim_set_view_organizationctx.edit: set_view_propertiescoveredscript covers it → retirement candidate (maintainer's call)
bim_set_phase_filterctx.edit: create_phase_filter, update_phase_filtercoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_phasectx.edit: delete_phasecoveredscript covers it → retirement candidate (maintainer's call)
bim_delete_phase_filterctx.edit: delete_phase_filtercoveredscript covers it → retirement candidate (maintainer's call)
bim_set_elementctx.edit: set_element_class, set_element_type, set_element_valuescoveredscript covers it → retirement candidate (maintainer's call)

parts ​

ToolScript equivalentStatusNote
bim_draft_part_from_cut_sheetnonehost stepreads a cut sheet with AI on the host
bim_read_picture_rowsnonehost stepreads a picture with AI on the host
bim_part_definition_examplebim_script_reference (Part definition recipe)coveredscript covers it → retirement candidate (maintainer's call)
bim_check_part_definitionPartBuilder.check; bim_check_outputcoveredscript covers it → retirement candidate (maintainer's call)
bim_read_part_definitionnonehost stepthe firm library is stored by the host
bim_save_part_definitionctx.parts.define + bim_save_part_typecoveredscript covers it → retirement candidate (maintainer's call)
bim_list_firm_partsnonehost stepthe firm library is stored by the host
bim_save_firm_partnonehost stepthe firm library is stored by the host
bim_set_clearancesPartBuilder.clearance; ctx.edit: set_part_clearancescoveredscript covers it → retirement candidate (maintainer's call)
bim_set_part_hostctx.edit: set_part_hostcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_mounting_planectx.edit: set_mounting_plane, create_mounting_planecoveredscript covers it → retirement candidate (maintainer's call)

calcs ​

ToolScript equivalentStatusNote
bim_list_calcsctx.calcs()coveredscript covers it → retirement candidate (maintainer's call)
bim_run_calcctx.calc({ calc, inputs, …edition })coveredname the code edition; the host's adopted codes are not read from a script; script covers it → retirement candidate (maintainer's call)
bim_suggest_duct_size`ctx.read("mechanical.duct_size",{ element_id })`covered
bim_pressure_reportctx.calc({ calc: "mech.duct_system_pressure" }) on the script's modelcoveredscript covers it → retirement candidate (maintainer's call)
bim_pipe_reportctx.calc({ calc: "plumbing.pipe_system" }) or plumbing.pressure_reportcoveredscript covers it → retirement candidate (maintainer's call)
bim_set_fitting_coefficient_overridectx.edit: set_fitting_coefficientcoveredscript covers it → retirement candidate (maintainer's call)
bim_size_pipesctx.calc({ calc: "plumbing.size_system" }), then ctx.edit: set_pipe_sizescoveredname the plumbing or fuel gas edition; script covers it → retirement candidate (maintainer's call)
bim_service_from_equipment_listctx.calc({ calc: "nec.service_size" }) with loads the script reads from ctx.modelcoveredscript covers it → retirement candidate (maintainer's call)

schedules ​

ToolScript equivalentStatusNote
bim_schedule_fieldsdocuments.scheduleFields(ctx, classes)covereda firm's own schedule-library classes come from the host's library (bim_library); script covers it → retirement candidate (maintainer's call)
bim_schedule_definedocuments.schedule; ctx.edit: create_view, edit_schedulecoveredscript covers it → retirement candidate (maintainer's call)
bim_schedule_edit_cellsctx.edit: set_element_values, set_parameterscoveredscript covers it → retirement candidate (maintainer's call)
bim_librarynonehost stepthe schedule library is stored by the host

Still to fill in the script API ​

Nothing: every tool is covered by a script or is a host step by design.

Stays a host step ​

  • bim_render_view_image: drawing pictures needs the host's renderer.
  • bim_render_sheet_image: drawing pictures needs the host's renderer.
  • bim_print_sheet_pdf: printing writes files through the host.
  • bim_print_view_pdf: printing writes files through the host.
  • bim_print_set_pdf: printing writes files through the host.
  • bim_issue_set: issuing records a set and its files in the host.
  • bim_lint_configure: lint settings are stored by the host.
  • bim_status_snapshot: prints and issues are the host's record.
  • bim_set_issue_status: issue status is recorded by the host's issuing.
  • bim_browse_autodesk_docs: reads another company's cloud through the host's connection.
  • bim_link_from_autodesk_docs: links an outside model through the host's connection.
  • bim_update_linked_model: fetches a new version through the host's connection.
  • bim_unlink_linked_model: the host keeps the link records.
  • bim_lint_accept_finding: accepted findings are stored by the host.
  • bim_lint_retract_acceptance: accepted findings are stored by the host.
  • bim_draft_part_from_cut_sheet: reads a cut sheet with AI on the host.
  • bim_read_picture_rows: reads a picture with AI on the host.
  • bim_read_part_definition: the firm library is stored by the host.
  • bim_list_firm_parts: the firm library is stored by the host.
  • bim_save_firm_part: the firm library is stored by the host.
  • bim_library: the schedule library is stored by the host.

Proof ​

packages/bim-mcp/__tests__/core-only-tasks.test.ts runs, with only the core tools on the server, one script each to: create sheets with a plan placed on each; make a schedule on a sheet; find a room from the walls around it; build, place and duct a rooftop unit; route a drain sized by the plumbing code with its slope; and tag elements in a plan. packages/bim-mcp/__tests__/core-only-gaps.test.ts does the same for the jobs that needed add-on tools: receptacles by code spacing, a room schedule, a schedule's numbers, a dwelling unit circuited from a room template with the panel's loads per phase, a phase rebalance, every duct tagged and dimensioned, a packed sheet, one-line diagrams (described and live), ducts sized from airflow, the clash check, levels from a linked model, the catalogues, and a duct height from the surfaces over it. The scripts are the worked examples bim_script_reference serves. packages/bim-mcp/__tests__/core-tool-budget.test.ts holds the default list to 10.

Apache License 2.0. The reference is generated from the code on every change.