pi-revit 0.2.7 → 0.2.9

package/scripts/uninstall.ps1

@@ -1,146 +1,146 @@
-#Requires -Version 5.1
-<#
-Removes everything the pi-revit install scripts placed on this PC:
-
-  - Revit bridge add-in:  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
-                          %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\
-  - Global command:       the pi-revit command next to the pi command
-  - Bridge runtime:       %APPDATA%\RevitBridge\ (per-start connection token / bridge.json)
-  - Pi package:           the pi-revit registration (pi remove), best-effort when pi is on PATH
-
-The workspace at Documents\pi-revit holds YOUR data (AGENTS.md notes, per-project
-session history) and is preserved by default. Pass -RemoveWorkspace to delete it too.
-
-Pi itself (the global coding agent) is yours to manage and is never touched.
-
-Close Revit before running. Idempotent — safe to re-run.
-
-Usage:
-  scripts\uninstall.ps1
-  scripts\uninstall.ps1 -RevitVersion 2027
-  scripts\uninstall.ps1 -RemoveWorkspace
-#>
-param(
-    [string]$RevitVersion = '',
-    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit'),
-    [switch]$RemoveWorkspace
-)
-
-$ErrorActionPreference = 'Stop'
-
-function Remove-IfExists {
-    param([string]$Path, [string]$Label)
-    if (Test-Path -LiteralPath $Path) {
-        Remove-Item -LiteralPath $Path -Recurse -Force
-        Write-Host "Removed $Label : $Path" -ForegroundColor Green
-    } else {
-        Write-Host "Not present, skipped $Label : $Path"
-    }
-}
-
-# 1. Revit add-in. With no -RevitVersion, sweep every Addins\<version> folder so the
-#    user need not remember which Revit they deployed to.
-$addinsRoot = Join-Path $env:APPDATA 'Autodesk\Revit\Addins'
-$versions = if ($RevitVersion) {
-    @($RevitVersion)
-} elseif (Test-Path -LiteralPath $addinsRoot) {
-    Get-ChildItem -LiteralPath $addinsRoot -Directory | ForEach-Object { $_.Name }
-} else {
-    @()
-}
-foreach ($v in $versions) {
-    $dir = Join-Path $addinsRoot $v
-    Remove-IfExists (Join-Path $dir 'RevitBridge.addin') "Revit $v add-in manifest"
-    Remove-IfExists (Join-Path $dir 'RevitBridge')       "Revit $v add-in folder"
-}
-
-# 2. Global pi-revit command next to the user's permanent pi. When this script runs
-#    from an npx cache or a node_modules copy, PATH may lead Get-Command to a pi shim
-#    inside that ephemeral tree first (see setup-workspace.ps1) — the launcher was
-#    never installed there, so resolve the permanent pi the same way setup does.
-function Get-PermanentPiCommand {
-    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
-    # short names (AHMAD~1.TAH) while $PSScriptRoot is normalized, and a form
-    # mismatch would silently defeat the own-tree exclusion.
-    function Resolve-LongPath([string]$p) {
-        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
-    }
-    $ownTree = $null
-    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
-    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
-    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
-    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
-        if (-not $_.Source) { return $false }
-        $src = Resolve-LongPath $_.Source
-        ($src -notmatch '\\_npx\\') -and
-        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
-    } | Select-Object -First 1
-}
-
-$pi = Get-Command pi -ErrorAction SilentlyContinue
-$piPermanent = Get-PermanentPiCommand
-if ($piPermanent) {
-    $binDir = Split-Path $piPermanent.Source -Parent
-    Remove-IfExists (Join-Path $binDir 'pi-revit.cmd') 'global pi-revit command'
-} else {
-    Write-Host 'No permanent pi found on PATH; skipping the global pi-revit command.'
-}
-
-# 3. Bridge runtime folder (connection token; recreated on each Revit start).
-Remove-IfExists (Join-Path $env:APPDATA 'RevitBridge') 'bridge runtime folder'
-
-# 4. Pi package registration. Pi keys a package by its install source: the npm
-#    installer (npx.cmd -y pi-revit) registers `npm:pi-revit`, while an install
-#    from a clone of this repo (`pi install ./`) registers the repo path resolved
-#    from the repo root. Try both forms; each succeeds only for the source that
-#    is actually registered, so a machine with both gets both removed.
-if ($pi) {
-    $repoRoot = Split-Path $PSScriptRoot -Parent
-    # When this script runs from the npm-installed copy, `pi remove npm:pi-revit`
-    # deletes the very folder the script lives in — and Windows fails that delete
-    # (EBUSY) while any working directory sits inside it. Step our own process out
-    # if needed; the calling shell's location we can only warn about.
-    if ($repoRoot -match '\\node_modules\\' -and
-        (Get-Location).Path.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
-        Set-Location $env:SystemRoot
-        Write-Warning "This PowerShell was started inside $repoRoot. If the package removal below fails, run 'cd \' in your shell and re-run the uninstall."
-    }
-    try {
-        $removed = @()
-        # './' resolves against the repo root, so it runs from there — and first,
-        # while this folder is guaranteed to still exist. 'npm:pi-revit' then runs
-        # from a neutral directory so no working directory blocks the folder delete.
-        foreach ($source in @('./', 'npm:pi-revit')) {
-            Push-Location $(if ($source -eq './') { $repoRoot } else { $env:SystemRoot })
-            try {
-                $global:LASTEXITCODE = 0
-                & pi remove $source
-                if ($LASTEXITCODE -eq 0) {
-                    $removed += $source
-                }
-            } finally {
-                Pop-Location
-            }
-        }
-        if ($removed.Count -gt 0) {
-            Write-Host "Removed the pi-revit Pi package ($($removed -join ', '))." -ForegroundColor Green
-        } else {
-            Write-Warning "No pi-revit Pi package registration was found. If pi still lists it, run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source)."
-        }
-    } catch {
-        Write-Warning "Could not auto-remove the Pi package; run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source). ($_)"
-    }
-}
-
-# 5. Workspace (user data) — opt-in only.
-if ($RemoveWorkspace) {
-    Remove-IfExists $WorkspaceDir 'workspace'
-} else {
-    Write-Host ''
-    Write-Host "Workspace preserved (your notes + session history): $WorkspaceDir" -ForegroundColor Yellow
-    Write-Host 'Pass -RemoveWorkspace to delete it too.'
-}
-
-Write-Host ''
-Write-Host 'pi-revit uninstalled. Pi itself is untouched; remove it yourself if you want:' -ForegroundColor Green
-Write-Host '  npm uninstall -g @earendil-works/pi-coding-agent'
+#Requires -Version 5.1
+<#
+Removes everything the pi-revit install scripts placed on this PC:
+
+  - Revit bridge add-in:  %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge.addin
+                          %APPDATA%\Autodesk\Revit\Addins\<version>\RevitBridge\
+  - Global command:       the pi-revit command next to the pi command
+  - Bridge runtime:       %APPDATA%\RevitBridge\ (per-start connection token / bridge.json)
+  - Pi package:           the pi-revit registration (pi remove), best-effort when pi is on PATH
+
+The workspace at Documents\pi-revit holds YOUR data (AGENTS.md notes, per-project
+session history) and is preserved by default. Pass -RemoveWorkspace to delete it too.
+
+Pi itself (the global coding agent) is yours to manage and is never touched.
+
+Close Revit before running. Idempotent — safe to re-run.
+
+Usage:
+  scripts\uninstall.ps1
+  scripts\uninstall.ps1 -RevitVersion 2027
+  scripts\uninstall.ps1 -RemoveWorkspace
+#>
+param(
+    [string]$RevitVersion = '',
+    [string]$WorkspaceDir = (Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'pi-revit'),
+    [switch]$RemoveWorkspace
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Remove-IfExists {
+    param([string]$Path, [string]$Label)
+    if (Test-Path -LiteralPath $Path) {
+        Remove-Item -LiteralPath $Path -Recurse -Force
+        Write-Host "Removed $Label : $Path" -ForegroundColor Green
+    } else {
+        Write-Host "Not present, skipped $Label : $Path"
+    }
+}
+
+# 1. Revit add-in. With no -RevitVersion, sweep every Addins\<version> folder so the
+#    user need not remember which Revit they deployed to.
+$addinsRoot = Join-Path $env:APPDATA 'Autodesk\Revit\Addins'
+$versions = if ($RevitVersion) {
+    @($RevitVersion)
+} elseif (Test-Path -LiteralPath $addinsRoot) {
+    Get-ChildItem -LiteralPath $addinsRoot -Directory | ForEach-Object { $_.Name }
+} else {
+    @()
+}
+foreach ($v in $versions) {
+    $dir = Join-Path $addinsRoot $v
+    Remove-IfExists (Join-Path $dir 'RevitBridge.addin') "Revit $v add-in manifest"
+    Remove-IfExists (Join-Path $dir 'RevitBridge')       "Revit $v add-in folder"
+}
+
+# 2. Global pi-revit command next to the user's permanent pi. When this script runs
+#    from an npx cache or a node_modules copy, PATH may lead Get-Command to a pi shim
+#    inside that ephemeral tree first (see setup-workspace.ps1) — the launcher was
+#    never installed there, so resolve the permanent pi the same way setup does.
+function Get-PermanentPiCommand {
+    # Long-form both sides of the prefix comparison: PATH entries may carry 8.3
+    # short names (SOMEUS~1.NAM) while $PSScriptRoot is normalized, and a form
+    # mismatch would silently defeat the own-tree exclusion.
+    function Resolve-LongPath([string]$p) {
+        try { (Get-Item -LiteralPath $p -ErrorAction Stop).FullName } catch { $p }
+    }
+    $ownTree = $null
+    $repoRoot = Resolve-LongPath (Split-Path $PSScriptRoot -Parent)
+    $idx = $repoRoot.LastIndexOf('\node_modules\', [StringComparison]::OrdinalIgnoreCase)
+    if ($idx -ge 0) { $ownTree = $repoRoot.Substring(0, $idx + '\node_modules\'.Length) }
+    Get-Command pi -All -ErrorAction SilentlyContinue | Where-Object {
+        if (-not $_.Source) { return $false }
+        $src = Resolve-LongPath $_.Source
+        ($src -notmatch '\\_npx\\') -and
+        (-not $ownTree -or -not $src.StartsWith($ownTree, [StringComparison]::OrdinalIgnoreCase))
+    } | Select-Object -First 1
+}
+
+$pi = Get-Command pi -ErrorAction SilentlyContinue
+$piPermanent = Get-PermanentPiCommand
+if ($piPermanent) {
+    $binDir = Split-Path $piPermanent.Source -Parent
+    Remove-IfExists (Join-Path $binDir 'pi-revit.cmd') 'global pi-revit command'
+} else {
+    Write-Host 'No permanent pi found on PATH; skipping the global pi-revit command.'
+}
+
+# 3. Bridge runtime folder (connection token; recreated on each Revit start).
+Remove-IfExists (Join-Path $env:APPDATA 'RevitBridge') 'bridge runtime folder'
+
+# 4. Pi package registration. Pi keys a package by its install source: the npm
+#    installer (npx.cmd -y pi-revit) registers `npm:pi-revit`, while an install
+#    from a clone of this repo (`pi install ./`) registers the repo path resolved
+#    from the repo root. Try both forms; each succeeds only for the source that
+#    is actually registered, so a machine with both gets both removed.
+if ($pi) {
+    $repoRoot = Split-Path $PSScriptRoot -Parent
+    # When this script runs from the npm-installed copy, `pi remove npm:pi-revit`
+    # deletes the very folder the script lives in — and Windows fails that delete
+    # (EBUSY) while any working directory sits inside it. Step our own process out
+    # if needed; the calling shell's location we can only warn about.
+    if ($repoRoot -match '\\node_modules\\' -and
+        (Get-Location).Path.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
+        Set-Location $env:SystemRoot
+        Write-Warning "This PowerShell was started inside $repoRoot. If the package removal below fails, run 'cd \' in your shell and re-run the uninstall."
+    }
+    try {
+        $removed = @()
+        # './' resolves against the repo root, so it runs from there — and first,
+        # while this folder is guaranteed to still exist. 'npm:pi-revit' then runs
+        # from a neutral directory so no working directory blocks the folder delete.
+        foreach ($source in @('./', 'npm:pi-revit')) {
+            Push-Location $(if ($source -eq './') { $repoRoot } else { $env:SystemRoot })
+            try {
+                $global:LASTEXITCODE = 0
+                & pi remove $source
+                if ($LASTEXITCODE -eq 0) {
+                    $removed += $source
+                }
+            } finally {
+                Pop-Location
+            }
+        }
+        if ($removed.Count -gt 0) {
+            Write-Host "Removed the pi-revit Pi package ($($removed -join ', '))." -ForegroundColor Green
+        } else {
+            Write-Warning "No pi-revit Pi package registration was found. If pi still lists it, run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source)."
+        }
+    } catch {
+        Write-Warning "Could not auto-remove the Pi package; run 'pi remove npm:pi-revit' (npm install) or 'pi remove ./' from this repo (install from source). ($_)"
+    }
+}
+
+# 5. Workspace (user data) — opt-in only.
+if ($RemoveWorkspace) {
+    Remove-IfExists $WorkspaceDir 'workspace'
+} else {
+    Write-Host ''
+    Write-Host "Workspace preserved (your notes + session history): $WorkspaceDir" -ForegroundColor Yellow
+    Write-Host 'Pass -RemoveWorkspace to delete it too.'
+}
+
+Write-Host ''
+Write-Host 'pi-revit uninstalled. Pi itself is untouched; remove it yourself if you want:' -ForegroundColor Green
+Write-Host '  npm uninstall -g @earendil-works/pi-coding-agent'

package/skills/pi-revit/SKILL.md

@@ -29,7 +29,8 @@ Workflow guidance:
 - Call `get_model_overview` first when starting work on an unfamiliar model — one call returns project metadata, units, levels, grids, and category counts.
 - `get_elements` is the listing/counting primitive (`count_only: true` for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with `get_element_details`. Prefer a `category` or `of_class` scope when filtering by a parameter's display name.
 - The selection pipeline is `get_elements` -> ids -> `manage_selection` (action `set`); there is no inline filter on selection.
-- `set_parameters` is the home for bulk parameter writes AND renames (the `Name` parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported.
+- `set_parameters` is the home for bulk parameter writes AND renames (the `Name` parameter covers levels, views, sheets, types). One transaction per batch; per-element failures are reported. Pass `expected_document` (the model title) when several models are open or the session is long — it makes the write fail cleanly instead of landing in a different active document.
+- Parameter display names are LOCALIZED: in a non-English Revit UI, `Mark` is `Kennzeichen` (German), `マーク` (Japanese), etc. When a display-name lookup or `parameter_names` filter finds nothing, or the document may be non-English, use the language-independent `BuiltInParameter` enum name instead (e.g. `ALL_MODEL_MARK` for Mark, `ALL_MODEL_INSTANCE_COMMENTS` for Comments) — `set_parameters`, `get_element_details.parameter_names`, and `get_elements` filter rules all accept them, and `get_element_details` reports each parameter's `builtInParameter` name for discovery.
 - Before writing `execute_csharp` code, verify unfamiliar classes/members with `search_api_docs` (works with no document open; first query builds the index and takes a few seconds). The top match carries its remarks, parameter docs, and returns inline, and every public API enum value is searchable — trust the result over guessing or web search; narrow the query to promote a different match into the top slot.
 - `export_documents` files its output under `Documents\pi-revit\Models\<model title>\exports` automatically when `output_dir` is omitted — keyed to the exported document, so it lands right even across many models. Pass `output_dir` only when the user names a different target.
 

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -72,6 +72,11 @@ namespace RevitBridge.Tools
                     type = "string",
                     description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp and Dump(value) are in scope. The final expression or a return statement is the result.",
                 },
+                expected_document = new
+                {
+                    type = "string",
+                    description = "Optional safety check: title of the document this script is meant for (as reported by get_model_overview). If the active document differs (user switched models), the call fails before running anything.",
+                },
             },
             required = new[] { "code" },
         };
@@ -88,6 +93,7 @@ namespace RevitBridge.Tools
             var doc = context.Document ?? throw new NoActiveDocumentException();
             var uiapp = context.UIApplication ?? throw new NoActiveDocumentException();
             var uidoc = uiapp.ActiveUIDocument ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
 
             string code = JsonArgs.GetString(args, "code") ?? string.Empty;
             if (string.IsNullOrWhiteSpace(code))

package/src/Revit/Tools/GetElementDetails.cs

@@ -27,7 +27,7 @@ namespace RevitBridge.Tools
                 {
                     type = "array",
                     items = new { type = "string" },
-                    description = "Only return these parameters (case-insensitive exact names). Default: all.",
+                    description = "Only return these parameters. Matches the display name OR the BuiltInParameter enum name (case-insensitive exact). Display names are localized (e.g. 'Mark' is 'Kennzeichen' in a German UI) — prefer enum names like ALL_MODEL_MARK for language-independent filtering. Default: all.",
                 },
                 include = new
                 {
@@ -101,12 +101,13 @@ namespace RevitBridge.Tools
                 };
 
                 int parameterCount = 0;
+                int parameterTotal = 0;
                 if (withParameters)
                 {
                     var parameters = new List<Dictionary<string, object?>>();
-                    AppendParameters(doc, element, nameFilter, isType: false, parameters);
+                    parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
                     if (withTypeParameters && elementType != null)
-                        AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
+                        parameterTotal += AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
                     dto["parameters"] = parameters;
                     parameterCount = parameters.Count;
                 }
@@ -119,7 +120,12 @@ namespace RevitBridge.Tools
                     dto["materials"] = DescribeMaterials(doc, element);
 
                 elements.Add(dto);
-                compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{(withParameters ? $", {parameterCount} params" : string.Empty)})");
+                // With a name filter active, "0 params" is ambiguous (none matched vs none
+                // exist): report matched-of-total so a localization miss is visible.
+                string paramSummary = !withParameters ? string.Empty
+                    : nameFilter != null ? $", {parameterCount} of {parameterTotal} params matched parameter_names"
+                    : $", {parameterCount} params";
+                compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{paramSummary})");
             }
 
             string compact = $"{elements.Count} element(s)"
@@ -131,18 +137,32 @@ namespace RevitBridge.Tools
             return new ToolOutput(new { count = elements.Count, elements, not_found = notFound }, compact);
         }
 
-        private static void AppendParameters(Document doc, Element element, HashSet<string>? nameFilter, bool isType, List<Dictionary<string, object?>> target)
+        /// <summary>Appends matching parameter rows and returns how many parameters the
+        /// element exposes in total (before the name filter).</summary>
+        private static int AppendParameters(Document doc, Element element, HashSet<string>? nameFilter, bool isType, List<Dictionary<string, object?>> target)
         {
             var rows = new List<Dictionary<string, object?>>();
+            int total = 0;
             foreach (Parameter parameter in element.Parameters)
             {
+                total++;
                 string name = parameter.Definition?.Name ?? string.Empty;
                 if (nameFilter != null && !nameFilter.Contains(name))
-                    continue;
+                {
+                    // Display names are localized; accept the language-independent
+                    // BuiltInParameter enum name (e.g. ALL_MODEL_MARK) as an alias.
+                    string? builtIn = parameter.Definition is InternalDefinition internalDefinition
+                        && internalDefinition.BuiltInParameter != BuiltInParameter.INVALID
+                        ? internalDefinition.BuiltInParameter.ToString()
+                        : null;
+                    if (builtIn is null || !nameFilter.Contains(builtIn))
+                        continue;
+                }
                 rows.Add(DescribeParameter(doc, parameter, name, isType));
             }
             rows.Sort((a, b) => string.Compare(a["name"] as string, b["name"] as string, StringComparison.OrdinalIgnoreCase));
             target.AddRange(rows);
+            return total;
         }
 
         private static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)

package/src/Revit/Tools/GetElements.cs

@@ -287,6 +287,14 @@ namespace RevitBridge.Tools
                     break;
             }
 
+            // Display-name promotion is only trustworthy inside one category/class: the
+            // probe sees just the first ProbeSize elements in collector order, so in an
+            // unscoped query a unanimous sample can still hide other categories further
+            // on whose same-named parameter has a different id — and a pinned quick rule
+            // would silently drop their matches.
+            bool scoped = !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "category"))
+                || !string.IsNullOrWhiteSpace(JsonArgs.GetString(args, "of_class"));
+
             foreach (var rule in rules)
             {
                 if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
@@ -296,12 +304,11 @@ namespace RevitBridge.Tools
                     continue;
                 // BuiltInParameter/guid rules address one global parameter id. A plain
                 // display name can resolve to DIFFERENT ids per category or family
-                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH), and a quick rule pinned
-                // to one exemplar's id would silently drop every other category's
-                // matches. Promote only when all probed elements agree on the id;
-                // otherwise the rule stays on the (per-element, correct) post-scan path.
+                // (e.g. 'Width' -> DOOR_WIDTH vs WINDOW_WIDTH). Promote a display-name
+                // rule only when the query is scoped AND all probed elements agree on
+                // the id; otherwise it stays on the (per-element, correct) post-scan path.
                 bool oneGlobalId = rule.BuiltIn != null || rule.SharedGuid != null
-                    || found.All(parameter => parameter!.Id == found[0]!.Id);
+                    || (scoped && found.All(parameter => parameter!.Id == found[0]!.Id));
                 if (oneGlobalId)
                     rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
             }

package/src/Revit/Tools/SearchApiDocs.cs

@@ -1,5 +1,6 @@
 using System.IO;
 using System.Text;
+using System.Text.RegularExpressions;
 using System.Text.Json;
 using System.Xml;
 using System.Xml.Linq;
@@ -124,7 +125,13 @@ namespace RevitBridge.Tools
 
         private static (List<ApiMember> Top, int Total) Search(DocIndex index, string query, char? kindFilter, int maxResults)
         {
+            // Signatures are rendered exactly one way ("Name(Type, Type)"): normalize the
+            // query's spacing around commas and parentheses so 'Wall.Create(Document,Curve'
+            // and 'Wall.Create( Document, Curve' hit the same rendered text instead of
+            // failing on typography.
             string q = query.ToLowerInvariant();
+            q = Regex.Replace(q, @"\s*,\s*", ", ");
+            q = Regex.Replace(q, @"\(\s+", "(");
             string[] words = q.Split(WordSeparators, StringSplitOptions.RemoveEmptyEntries);
 
             var scored = new List<(ApiMember Member, int Score)>();
@@ -215,11 +222,12 @@ namespace RevitBridge.Tools
             return markdown.ToString();
         }
 
-        /// <summary>The model sees only this markdown — details.payload never reaches it —
-        /// so the top match carries its remarks, parameter, return, and exception docs
-        /// inline (capped for display; the payload keeps full text). Lines that would blow
-        /// the markdown budget are dropped individually. When the top match is one of
-        /// several same-named overloads, a note says how to target another one.</summary>
+        /// <summary>The model can read details.payload (the cap note above even points it
+        /// there), but this markdown is what lands in the strongest-attention position of
+        /// the tool result — so the top match carries its remarks, parameter, return, and
+        /// exception docs inline (capped for display; the payload keeps full text). Lines
+        /// that would blow the markdown budget are dropped individually. When the top match
+        /// is one of several same-named overloads, a note says how to target another one.</summary>
         private static void AppendTopMatchDocs(StringBuilder markdown, ApiMember member, int overloadCount)
         {
             var lines = new List<string>(5);

package/src/Revit/Tools/SetParameters.cs

@@ -44,6 +44,11 @@ namespace RevitBridge.Tools
                         required = new[] { "element_id", "parameter", "value" },
                     },
                 },
+                expected_document = new
+                {
+                    type = "string",
+                    description = "Optional safety check: title of the document these writes are meant for (as reported by get_model_overview). If the active document differs (user switched models), the call fails without changing anything.",
+                },
             },
             required = new[] { "updates" },
         };
@@ -58,6 +63,7 @@ namespace RevitBridge.Tools
         public object? Execute(JsonElement args, ToolContext context)
         {
             var doc = context.Document ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
             var updates = ParseUpdates(args);
 
             var succeeded = new List<Dictionary<string, object?>>();