pi-revit 0.2.10 → 0.2.12

package/CHANGELOG.md

@@ -7,6 +7,40 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
 describing what the user will notice — not internal refactors.
 
+## [0.2.12] - 2026-07-22
+
+### Added
+- New tool `open_view`: activates a view or sheet in the Revit UI — the equivalent of
+  double-clicking it in the Project Browser. Identify the target by `view_id` or by
+  `name` (view name, sheet number like "A-101", or "number - name"). Uses Revit's
+  queued `RequestViewChange`, which is explicitly legal from the bridge's ExternalEvent
+  context; the activation completes the instant the call returns. Ends the
+  "please double-click the sheet yourself" gap after sheet/view creation.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
+## [0.2.11] - 2026-07-22
+
+### Fixed
+- `search_api_docs`: signature queries now accept .NET type names and qualified names —
+  `Wall.Create(Document, Curve, ElementId, Boolean` and `...(System.String` match the
+  rendered `bool` / `string`, and `(Autodesk.Revit.DB.Document` matches `Document`.
+  Parameter types in the query are reduced exactly the way the index renders them
+  (namespace stripped, CLR name → C# keyword, case-insensitive).
+- `search_api_docs`: Creation-factory calls resolve — `Document.Create.NewRoom(Level, UV`
+  finds `Document.NewRoom`, and `Document.Create.NewFamilyInstance` finds the
+  `ItemFactoryBase` overloads (factory members documented on a base class). A note in the
+  result explains the rewrite. Applies only to the literal `Document.Create.` /
+  `Application.Create.` prefixes; ordinary members like `Wall.Create` are untouched, and
+  nonsense like `Document.Create.Banana` still honestly returns nothing.
+
+Both were observed live: pi stumbled on these five times across two modeling sessions.
+The benchmark gained six regression probes for them.
+
+Requires redeploying the Revit add-in (`scripts\deploy.ps1` with Revit closed, then
+restart Revit).
+
 ## [0.2.10] - 2026-07-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",

package/scripts/benchmark-search-docs.py

@@ -80,7 +80,8 @@ class Member:
     @property
     def short_sig_prefix(s):
         shorts = [short_type(p) for p in s.params]
-        return f"{s.typename}.{s.member}(" + ", ".join(shorts)
+        head = s.typename if s.member == "#ctor" else f"{s.typename}.{s.member}"
+        return f"{head}(" + ", ".join(shorts)
 
 def text_of(el):
     if el is None: return None
@@ -161,7 +162,8 @@ for m in sampleB:
     matches, _ = search(canonical)
     B["n"] += 1
     sigs = [x.get("signature","") for x in matches]
-    ok = bool(sigs and sigs[0].startswith(f"{m.typename}.{m.member}("))
+    want = f"new {m.typename}(" if m.member == "#ctor" else f"{m.typename}.{m.member}("
+    ok = bool(sigs and sigs[0].startswith(want))
     B["top1_sig"] += ok
     variants = [canonical.replace(", ", ","),
                 canonical.replace(", ", " , "),
@@ -200,6 +202,13 @@ probe("case-insensitive", "wall.create(document, curve")
 probe("Double vs double", "UnitUtils.ConvertToInternalUnits(Double, ForgeTypeId")
 probe("trailing garbage brackets", "Wall.Create(Document, Curve]]", True)  # observational
 probe("double periods", "Wall..Create", True)  # observational
+# 0.2.11: CLR alias + namespace reduction in signature queries, Creation-factory rewrite
+probe("CLR alias Boolean", "Wall.Create(Document, Curve, ElementId, Boolean")
+probe("qualified param type", "Wall.Create(Autodesk.Revit.DB.Document, Curve")
+probe("System-qualified alias", "ParameterFilterElement.Create(Document, System.String")
+probe("factory rewrite", "Document.Create.NewRoom(Level, UV")
+probe("factory inherited member", "Document.Create.NewFamilyInstance")
+probe("factory honesty control", "Document.Create.Banana", expect_nonzero=False)
 print("C done", flush=True)
 R["C complex-syntax"] = C
 

package/skills/pi-revit/SKILL.md

@@ -1,52 +1,53 @@
----
-name: pi-revit
-description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
----
-
-# Revit
-
-Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only `ping` and `search_api_docs` work without a document).
-
-## Tool selection
-
-| Task | Tool |
-|------|------|
-| Bridge alive? Which Revit version? | `ping` |
-| Orientation: project info, units, levels, grids, category counts | `get_model_overview` |
-| List or count elements of ANY category (walls, doors, rooms, sheets, views, ...) | `get_elements` |
-| Read parameter VALUES, location, bounding box, materials of specific elements | `get_element_details` |
-| List element types / family symbols; "used vs merely loaded" | `get_element_types` |
-| Read or change the user's selection; zoom; temporary isolate | `manage_selection` |
-| Write parameter values; rename anything (levels, views, sheets, types) | `set_parameters` |
-| Look up Revit API classes/members/signatures | `search_api_docs` |
-| Everything else (create, delete, move, views, sheets, tagging, ...) | `execute_csharp` |
-| PNG snapshot of a view (visual QA) | `capture_view` (advanced) |
-| PDF/DWG/PNG/IFC file export | `export_documents` (advanced) |
-| Warnings / model quality audit | `get_model_health` (advanced) |
-
-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. 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.
-
-## execute_csharp playbook
-
-- Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
-- The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own `Transaction` (sub-transactions are fine).
-- Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
-- Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
-- Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
-- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in `suppressedDialogs`.
-- `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
-
-## Failure modes
-
-- **Bridge not reachable** ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry `ping`.
-- **HTTP 409 / "No active Revit document is open."** (`hasActiveDocument: false`): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
-- **Timeout** ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. `get_elements`) before re-issuing a write.
-- **Cancelled**: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.
+---
+name: pi-revit
+description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health). Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
+---
+
+# Revit
+
+Work with the live Revit model. The tools call a headless bridge add-in inside Revit (2025, 2026, or 2027); Revit must be running with a project open (only `ping` and `search_api_docs` work without a document).
+
+## Tool selection
+
+| Task | Tool |
+|------|------|
+| Bridge alive? Which Revit version? | `ping` |
+| Orientation: project info, units, levels, grids, category counts | `get_model_overview` |
+| List or count elements of ANY category (walls, doors, rooms, sheets, views, ...) | `get_elements` |
+| Read parameter VALUES, location, bounding box, materials of specific elements | `get_element_details` |
+| List element types / family symbols; "used vs merely loaded" | `get_element_types` |
+| Read or change the user's selection; zoom; temporary isolate | `manage_selection` |
+| Put a view or sheet on the user's screen (activate it) | `open_view` |
+| Write parameter values; rename anything (levels, views, sheets, types) | `set_parameters` |
+| Look up Revit API classes/members/signatures | `search_api_docs` |
+| Everything else (create, delete, move, views, sheets, tagging, ...) | `execute_csharp` |
+| PNG snapshot of a view (visual QA) | `capture_view` (advanced) |
+| PDF/DWG/PNG/IFC file export | `export_documents` (advanced) |
+| Warnings / model quality audit | `get_model_health` (advanced) |
+
+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. 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.
+
+## execute_csharp playbook
+
+- Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
+- The transaction is automatic: the whole script runs inside ONE backend-owned transaction — committed on success, rolled back on any exception. Do not open your own `Transaction` (sub-transactions are fine).
+- Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
+- Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
+- Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
+- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops — the budget is 120s and Revit cannot be interrupted mid-script; modal dialogs are auto-dismissed and reported in `suppressedDialogs`.
+- `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
+
+## Failure modes
+
+- **Bridge not reachable** ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry `ping`.
+- **HTTP 409 / "No active Revit document is open."** (`hasActiveDocument: false`): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
+- **Timeout** ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. `get_elements`) before re-issuing a write.
+- **Cancelled**: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.

package/src/Revit/ToolRegistry.cs

@@ -71,6 +71,7 @@ namespace RevitBridge
             registry.Add(new GetElementTypes());
             registry.Add(new GetElementDetails());
             registry.Add(new ManageSelection());
+            registry.Add(new OpenView());
             registry.Add(new SetParameters());
             registry.Add(new CaptureView());
             registry.Add(new ExportDocuments());

package/src/Revit/Tools/OpenView.cs

@@ -0,0 +1,103 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Activates a view or sheet in the Revit UI — the API equivalent of double-clicking
+    /// it in the Project Browser. Uses UIDocument.RequestViewChange, which is explicitly
+    /// permitted from an ExternalEvent callback (where all bridge tools run) as long as no
+    /// transaction is open; the tool opens none. The activation is asynchronous by design:
+    /// Revit performs it the moment control returns from the bridge call.
+    /// </summary>
+    internal sealed class OpenView : ITool
+    {
+        public string Name => "open_view";
+        public string Label => "Open View";
+        public string Description => "Activate a view or sheet in the Revit UI, like double-clicking it in the Project Browser. Identify the target by view_id (an id from get_elements category Views/Sheets or from view/sheet creation) or by name (exact view name, sheet number like 'A-101', or sheet number - name; case-insensitive). Activation is queued and completes the instant this call returns control to Revit — a capture_view immediately after may still show the previous active view. View templates and internal views cannot be opened.";
+        public bool Write => false;
+
+        public object ParametersSchema => new
+        {
+            type = "object",
+            properties = new
+            {
+                view_id = new { type = "integer", description = "Id of the view or sheet to activate." },
+                name = new { type = "string", description = "Exact view name, sheet number, or sheet 'number - name' (case-insensitive). Used when view_id is absent." },
+            },
+        };
+
+        public string? PromptSnippet => "Activate a Revit view or sheet in the UI by id or name (like double-clicking it in the Project Browser).";
+        public IReadOnlyList<string>? PromptGuidelines => new[]
+        {
+            "Use open_view to put a view or sheet on the user's screen (e.g. after creating a sheet); activation completes right after the call, so capture_view in the SAME call batch may still show the old view.",
+        };
+
+        public object? Execute(JsonElement args, ToolContext context)
+        {
+            var doc = context.Document ?? throw new NoActiveDocumentException();
+            var uiapp = context.UIApplication ?? throw new NoActiveDocumentException();
+            var uidoc = uiapp.ActiveUIDocument ?? throw new NoActiveDocumentException();
+
+            long? viewId = JsonArgs.GetLong(args, "view_id");
+            string? name = JsonArgs.GetString(args, "name");
+            if (viewId is null && string.IsNullOrWhiteSpace(name))
+                throw new ArgumentException("Pass view_id or name to identify the view or sheet to open.");
+
+            View view = viewId is { } id ? ResolveById(doc, id) : ResolveByName(doc, name!.Trim());
+
+            try
+            {
+                uidoc.RequestViewChange(view);
+            }
+            catch (Autodesk.Revit.Exceptions.ArgumentException ex)
+            {
+                throw new ArgumentException($"View '{view.Name}' (id {view.Id.Value}) cannot be activated: {ex.Message}");
+            }
+            catch (Autodesk.Revit.Exceptions.InvalidOperationException ex)
+            {
+                throw new InvalidOperationException(
+                    $"Revit refused to queue the view change to '{view.Name}': {ex.Message} "
+                    + "The document may be mid-edit; retry after the current operation finishes.");
+            }
+
+            string kind = view is ViewSheet sheet ? $"sheet {sheet.SheetNumber}" : view.ViewType.ToString();
+            return new ToolOutput(new
+            {
+                requestedViewId = view.Id.Value,
+                viewName = view.Name,
+                viewType = view.ViewType.ToString(),
+            }, $"Queued activation of {kind} '{view.Name}' (id {view.Id.Value}); it opens as soon as Revit regains control.");
+        }
+
+        private static View ResolveById(Document doc, long id)
+        {
+            var view = doc.GetElement(new ElementId(id)) as View
+                ?? throw new ArgumentException($"Element {id} is not a view or sheet (or does not exist). Find view ids with get_elements, category 'Views' or 'Sheets'.");
+            if (view.IsTemplate)
+                throw new ArgumentException($"View '{view.Name}' (id {id}) is a view template; templates cannot be opened.");
+            return view;
+        }
+
+        private static View ResolveByName(Document doc, string name)
+        {
+            var candidates = new FilteredElementCollector(doc)
+                .OfClass(typeof(View))
+                .Cast<View>()
+                .Where(view => !view.IsTemplate)
+                .Where(view =>
+                    string.Equals(view.Name, name, StringComparison.OrdinalIgnoreCase)
+                    || (view is ViewSheet sheet
+                        && (string.Equals(sheet.SheetNumber, name, StringComparison.OrdinalIgnoreCase)
+                            || string.Equals($"{sheet.SheetNumber} - {sheet.Name}", name, StringComparison.OrdinalIgnoreCase))))
+                .ToList();
+
+            if (candidates.Count == 1)
+                return candidates[0];
+            if (candidates.Count == 0)
+                throw new ArgumentException($"No view or sheet named '{name}'. Find the exact name or sheet number with get_elements, category 'Views' or 'Sheets'.");
+            string list = string.Join("; ", candidates.Take(8).Select(view => $"'{view.Name}' (id {view.Id.Value}, {view.ViewType})"));
+            throw new ArgumentException($"'{name}' matches {candidates.Count} views: {list}. Pass view_id to disambiguate.");
+        }
+    }
+}

package/src/Revit/Tools/SearchApiDocs.cs

@@ -81,7 +81,7 @@ namespace RevitBridge.Tools
             if (index.Members.Count == 0)
                 throw new InvalidOperationException("The Revit API documentation index is empty. " + string.Join(" ", index.Warnings));
 
-            var (top, total) = Search(index, query, kindFilter, maxResults);
+            var (top, total, rewriteNote) = Search(index, query, kindFilter, maxResults);
 
             var matches = new List<Dictionary<string, object?>>(top.Count);
             for (int i = 0; i < top.Count; i++)
@@ -116,22 +116,56 @@ namespace RevitBridge.Tools
                 indexedMembers = index.Members.Count,
                 sources = index.SourceFiles,
                 warnings = index.Warnings.Count > 0 ? index.Warnings : null,
-            }, BuildMarkdown(query, top, total, index));
+            }, BuildMarkdown(query, top, total, index) + (rewriteNote is null ? string.Empty : $"\nNote: {rewriteNote}"));
         }
 
         // ----------------------------------------------------------------- search
 
         private static readonly char[] WordSeparators = { '.', ' ', '_', '(', ')', ',', ':', '-', '/' };
 
-        private static (List<ApiMember> Top, int Total) Search(DocIndex index, string query, char? kindFilter, int maxResults)
+        private static (List<ApiMember> Top, int Total, string? RewriteNote) 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();
+            // failing on typography. Parameter types are additionally reduced the same way
+            // the renderer reduces them (namespaces stripped, CLR names -> C# keywords), so
+            // 'Wall.Create(Document, Curve, ElementId, Boolean' and
+            // '...(System.String' match the rendered 'bool' / 'string'.
+            string q = NormalizeSignatureQuery(query).ToLowerInvariant();
             q = Regex.Replace(q, @"\s*,\s*", ", ");
             q = Regex.Replace(q, @"\(\s+", "(");
+
+            // The Creation-factory pattern: code says doc.Create.NewRoom(...) but the docs
+            // live on Autodesk.Revit.Creation.Document (rendered 'Document.NewRoom') or a
+            // base class like ItemFactoryBase. Try the factory rewrite, then the bare
+            // member, before giving up. Deterministic rewrites of an exact idiom — never
+            // applied unless the literal 'document.create.' / 'application.create.' prefix
+            // is present, so ordinary names like Wall.Create are untouched.
+            var candidates = new List<(string Query, string? Note)> { (q, null) };
+            foreach (string factory in new[] { "document.create.", "application.create." })
+            {
+                if (!q.StartsWith(factory, StringComparison.Ordinal))
+                    continue;
+                string owner = factory[..(factory.IndexOf('.') + 1)];         // "document."
+                string rest = q[factory.Length..];
+                candidates.Add((owner + rest, $"'{owner}Create.*' is the Creation factory — matched as '{owner}{rest}'."));
+                string bareMember = rest.Split('(')[0];
+                if (bareMember.Length > 0)
+                    candidates.Add((bareMember, $"'{owner}Create.{bareMember}' is a Creation-factory call; its docs live on the factory class (e.g. ItemFactoryBase) — matched by member name '{bareMember}'."));
+            }
+
+            foreach (var (candidate, note) in candidates)
+            {
+                var (top, total) = RunScoring(index, candidate, kindFilter, maxResults);
+                if (total > 0)
+                    return (top, total, note);
+            }
+            return (new List<ApiMember>(), 0, null);
+        }
+
+        private static (List<ApiMember> Top, int Total) RunScoring(DocIndex index, string q, char? kindFilter, int maxResults)
+        {
             string[] words = q.Split(WordSeparators, StringSplitOptions.RemoveEmptyEntries);
 
             var scored = new List<(ApiMember Member, int Score)>();
@@ -155,6 +189,65 @@ namespace RevitBridge.Tools
             return (top, scored.Count);
         }
 
+        /// <summary>Reduces the parameter part of a signature query exactly the way the
+        /// renderer reduces signatures: each identifier keeps only its last dot-segment
+        /// and CLR primitive names map to C# keywords (case-insensitively — queries say
+        /// 'Boolean' or 'boolean'; signatures render 'bool'). The member path before the
+        /// first '(' is left untouched.</summary>
+        private static string NormalizeSignatureQuery(string query)
+        {
+            int paren = query.IndexOf('(');
+            if (paren < 0)
+                return query;
+
+            string tail = query[(paren + 1)..];
+            var result = new StringBuilder(tail.Length);
+            int i = 0;
+            while (i < tail.Length)
+            {
+                char c = tail[i];
+                if (char.IsLetter(c) || c == '_')
+                {
+                    int start = i, lastDot = -1;
+                    while (i < tail.Length && (char.IsLetterOrDigit(tail[i]) || tail[i] is '_' or '.'))
+                    {
+                        if (tail[i] == '.')
+                            lastDot = i;
+                        i++;
+                    }
+                    string identifier = tail[(lastDot >= 0 ? lastDot + 1 : start)..i];
+                    result.Append(QueryTypeAliases.TryGetValue(identifier, out string? keyword) ? keyword : identifier);
+                }
+                else
+                {
+                    result.Append(c);
+                    i++;
+                }
+            }
+            return query[..(paren + 1)] + result;
+        }
+
+        /// <summary>Case-insensitive inverse of MapTypeKeyword for query text.</summary>
+        private static readonly Dictionary<string, string> QueryTypeAliases = new(StringComparer.OrdinalIgnoreCase)
+        {
+            ["String"] = "string",
+            ["Boolean"] = "bool",
+            ["Int32"] = "int",
+            ["Int64"] = "long",
+            ["Int16"] = "short",
+            ["Double"] = "double",
+            ["Single"] = "float",
+            ["Object"] = "object",
+            ["Void"] = "void",
+            ["Byte"] = "byte",
+            ["SByte"] = "sbyte",
+            ["Char"] = "char",
+            ["Decimal"] = "decimal",
+            ["UInt16"] = "ushort",
+            ["UInt32"] = "uint",
+            ["UInt64"] = "ulong",
+        };
+
         private static int Score(ApiMember member, string q, string[] words)
         {
             // A query with a parenthesis targets a specific overload by signature,