structured-world
diff --git a/‎src/handlers.ts‎
Lines changed: 4 additions & 0 deletions b/‎src/handlers.ts‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎src/registry-manager.ts‎
Lines changed: 23 additions & 3 deletions b/‎src/registry-manager.ts‎
Lines changed: 23 additions & 3 deletions
diff --git a/‎src/services/ToolAvailability.ts‎
Lines changed: 81 additions & 0 deletions b/‎src/services/ToolAvailability.ts‎
Lines changed: 81 additions & 0 deletions
diff --git a/‎src/utils/schema-utils.ts‎
Lines changed: 57 additions & 0 deletions b/‎src/utils/schema-utils.ts‎
Lines changed: 57 additions & 0 deletions
diff --git a/‎tests/unit/RegistryManager.test.ts‎
Lines changed: 117 additions & 0 deletions b/‎tests/unit/RegistryManager.test.ts‎
Lines changed: 117 additions & 0 deletions
@@ -305,6 +305,10 @@ export async function setupHandlers(server: Server): Promise<void> {
 
           const instanceInfo = connectionManager.getInstanceInfo();
           logger.info(`Connection initialized: ${instanceInfo.version} ${instanceInfo.tier}`);
+
+          // Rebuild registry cache now that tier/version info is available
+          const { RegistryManager } = await import("./registry-manager");
+          RegistryManager.getInstance().refreshCache();
         } catch (initError) {
           logger.error(
             `Connection initialization failed: ${initError instanceof Error ? initError.message : String(initError)}`
 
@@ -52,9 +52,12 @@ import {
   getToolDescriptionOverrides,
 } from "./config";
 import { ToolAvailability } from "./services/ToolAvailability";
+import { ConnectionManager } from "./services/ConnectionManager";
+import type { GitLabTier } from "./services/GitLabVersionDetector";
 import { logger } from "./logger";
 import {
   transformToolSchema,
+  stripTierRestrictedParameters,
   shouldRemoveTool,
   extractActionsFromSchema,
 } from "./utils/schema-utils";
@@ -269,6 +272,15 @@ class RegistryManager {
   private buildToolLookupCache(): void {
     this.toolLookupCache.clear();
 
+    // Pre-fetch instance info once per cache build to avoid redundant calls
+    let instanceInfo: { tier: GitLabTier; version: string } | undefined;
+    try {
+      const info = ConnectionManager.getInstance().getInstanceInfo();
+      instanceInfo = { tier: info.tier, version: info.version };
+    } catch {
+      // Connection not initialized - parameter restrictions won't apply
+    }
+
     for (const registry of this.registries.values()) {
       for (const [toolName, tool] of registry) {
         // Apply GITLAB_READ_ONLY_MODE filtering at registry level
@@ -301,7 +313,15 @@ class RegistryManager {
         let finalTool = tool;
 
         // Transform schema to remove denied actions and apply description overrides
-        const transformedSchema = transformToolSchema(toolName, tool.inputSchema);
+        let transformedSchema = transformToolSchema(toolName, tool.inputSchema);
+
+        // Strip tier-restricted parameters from schema (skip if connection not initialized)
+        if (instanceInfo) {
+          const restrictedParams = ToolAvailability.getRestrictedParameters(toolName, instanceInfo);
+          if (restrictedParams.length > 0) {
+            transformedSchema = stripTierRestrictedParameters(transformedSchema, restrictedParams);
+          }
+        }
 
         // Apply tool-level description override if available
         const customDescription = this.descriptionOverrides.get(toolName);
@@ -356,10 +376,10 @@ class RegistryManager {
   }
 
   /**
-   * Clear all caches and rebuild
+   * Clear all caches and rebuild (e.g., after ConnectionManager init provides tier/version)
    */
   public refreshCache(): void {
-    this.buildToolLookupCache();
+    this.invalidateCaches();
   }
 
   /**
 
@@ -18,6 +18,13 @@ interface ActionRequirement {
   notes?: string;
 }
 
+/**
+ * Parameter-level tier/version requirement.
+ * Same structure as ActionRequirement; aliased for semantic clarity
+ * when used in parameterRequirements map.
+ */
+type ParameterRequirement = ActionRequirement;
+
 /**
  * Tool with action-level requirements (for consolidated tools)
  */
@@ -726,6 +733,80 @@ export class ToolAvailability {
     },
   };
 
+  // ============================================================================
+  // Per-Parameter Tier Requirements
+  // ============================================================================
+
+  /**
+   * Parameter-level requirements for tools with tier-gated parameters.
+   * Parameters listed here will be stripped from the JSON Schema when the
+   * detected instance tier/version is insufficient.
+   */
+  private static parameterRequirements: Record<string, Record<string, ParameterRequirement>> = {
+    manage_work_item: {
+      weight: { tier: "premium", minVersion: "15.0", notes: "Work item weight widget" },
+      iterationId: { tier: "premium", minVersion: "15.0", notes: "Iteration widget" },
+      healthStatus: { tier: "ultimate", minVersion: "15.0", notes: "Health status widget" },
+    },
+  };
+
+  /**
+   * Get list of parameter names that should be REMOVED from the schema
+   * for the current instance tier and version.
+   *
+   * @param toolName - Tool name to check parameter requirements for
+   * @returns Array of parameter names that should be stripped from the schema
+   */
+  public static getRestrictedParameters(
+    toolName: string,
+    cachedInstanceInfo?: { tier: GitLabTier; version: string }
+  ): string[] {
+    const paramReqs = this.parameterRequirements[toolName];
+    if (!paramReqs) return [];
+
+    let instanceTier: GitLabTier;
+    let instanceVersion: number;
+    let rawVersion: string;
+
+    if (cachedInstanceInfo) {
+      instanceTier = cachedInstanceInfo.tier;
+      rawVersion = cachedInstanceInfo.version;
+      instanceVersion = parseVersion(rawVersion);
+    } else {
+      const connectionManager = ConnectionManager.getInstance();
+      try {
+        const instanceInfo = connectionManager.getInstanceInfo();
+        instanceTier = instanceInfo.tier;
+        rawVersion = instanceInfo.version;
+        instanceVersion = parseVersion(rawVersion);
+      } catch {
+        // Connection not initialized - don't restrict anything
+        return [];
+      }
+    }
+
+    const restricted: string[] = [];
+    const actualTierLevel = this.TIER_ORDER[instanceTier] ?? 0;
+
+    for (const [paramName, req] of Object.entries(paramReqs)) {
+      const requiredTierLevel = this.TIER_ORDER[req.tier] ?? 0;
+      const requiredVersion = parseVersion(req.minVersion);
+
+      // Parameter is restricted if tier is insufficient OR version is too low
+      if (actualTierLevel < requiredTierLevel || instanceVersion < requiredVersion) {
+        restricted.push(paramName);
+      }
+    }
+
+    if (restricted.length > 0) {
+      logger.debug(
+        `Tool '${toolName}': restricted parameters for tier=${instanceTier}, version=${rawVersion}: [${restricted.join(", ")}]`
+      );
+    }
+
+    return restricted;
+  }
+
   /**
    * Get requirement for a tool, optionally with action
    */
 
@@ -431,6 +431,63 @@ function filterFlatSchemaActions(schema: JSONSchema, toolName: string): JSONSche
   return result;
 }
 
+// ============================================================================
+// Parameter-Level Tier Filtering
+// ============================================================================
+
+/**
+ * Strip tier-restricted parameters from a JSON Schema.
+ * Removes properties and their required entries for parameters that are
+ * unavailable at the current GitLab instance tier/version.
+ *
+ * Works with both flat schemas and discriminated unions (oneOf).
+ *
+ * @param schema - JSON schema (already transformed by the main pipeline)
+ * @param restrictedParams - Parameter names to remove from the schema
+ * @returns Schema with restricted parameters removed
+ */
+export function stripTierRestrictedParameters(
+  schema: JSONSchema,
+  restrictedParams: string[]
+): JSONSchema {
+  if (restrictedParams.length === 0) {
+    return schema;
+  }
+
+  // Deep clone to avoid mutating original
+  const result = JSON.parse(JSON.stringify(schema)) as JSONSchema;
+  const restrictedSet = new Set(restrictedParams);
+
+  if (result.oneOf) {
+    // Discriminated union: strip from each branch
+    for (const branch of result.oneOf) {
+      stripFromProperties(branch, restrictedSet);
+    }
+  } else {
+    // Flat schema: strip from top-level properties
+    stripFromProperties(result, restrictedSet);
+  }
+
+  return result;
+}
+
+/**
+ * Remove restricted parameters from a schema object's properties and required array
+ */
+function stripFromProperties(schema: JSONSchema, restrictedParams: Set<string>): void {
+  if (schema.properties) {
+    for (const paramName of restrictedParams) {
+      if (paramName in schema.properties) {
+        delete schema.properties[paramName];
+      }
+    }
+  }
+
+  if (schema.required) {
+    schema.required = schema.required.filter(name => !restrictedParams.has(name));
+  }
+}
+
 // ============================================================================
 // Utility Functions
 // ============================================================================
 
@@ -72,6 +72,15 @@ jest.mock("../../src/services/ToolAvailability", () => ({
   ToolAvailability: {
     isToolAvailable: jest.fn(),
     getUnavailableReason: jest.fn(),
+    getRestrictedParameters: jest.fn().mockReturnValue([]),
+  },
+}));
+
+jest.mock("../../src/services/ConnectionManager", () => ({
+  ConnectionManager: {
+    getInstance: jest.fn().mockReturnValue({
+      getInstanceInfo: jest.fn().mockReturnValue({ tier: "free", version: "17.0.0" }),
+    }),
   },
 }));
 
@@ -322,6 +331,114 @@ describe("RegistryManager", () => {
       expect(names).toContain("core_tool_1");
       expect(names).not.toContain("unavailable_tool");
     });
+
+    it("should strip tier-restricted parameters from tool schema", () => {
+      // Add a tool with properties to test parameter stripping
+      const coreRegistry = require("../../src/entities/core/registry").coreToolRegistry;
+      coreRegistry.set("tool_with_params", {
+        name: "tool_with_params",
+        description: "Tool with tier-gated params",
+        inputSchema: {
+          type: "object",
+          properties: {
+            action: { type: "string", enum: ["create"] },
+            title: { type: "string" },
+            weight: { type: "number", description: "Premium param" },
+            healthStatus: { type: "string", description: "Ultimate param" },
+          },
+          required: ["action", "title", "weight"],
+        },
+        handler: jest.fn(),
+      });
+
+      try {
+        // Make getRestrictedParameters return restricted params for this tool
+        ToolAvailability.getRestrictedParameters.mockImplementation((toolName: string) =>
+          toolName === "tool_with_params" ? ["weight", "healthStatus"] : []
+        );
+
+        (RegistryManager as any).instance = null;
+        registryManager = RegistryManager.getInstance();
+
+        const tool = registryManager.getTool("tool_with_params");
+        expect(tool).toBeDefined();
+
+        const schema = tool?.inputSchema as any;
+
+        // Restricted properties should be removed
+        expect(schema.properties?.weight).toBeUndefined();
+        expect(schema.properties?.healthStatus).toBeUndefined();
+
+        // Non-restricted properties should remain
+        expect(schema.properties?.action).toBeDefined();
+        expect(schema.properties?.title).toBeDefined();
+
+        // weight was in required, should be removed
+        expect(schema.required).not.toContain("weight");
+        expect(schema.required).toContain("action");
+        expect(schema.required).toContain("title");
+      } finally {
+        coreRegistry.delete("tool_with_params");
+      }
+    });
+
+    it("should skip parameter stripping when ConnectionManager is not initialized", () => {
+      const { ConnectionManager } = require("../../src/services/ConnectionManager");
+      const coreRegistry = require("../../src/entities/core/registry").coreToolRegistry;
+
+      coreRegistry.set("tool_with_params", {
+        name: "tool_with_params",
+        description: "Tool with tier-gated params",
+        inputSchema: {
+          type: "object",
+          properties: {
+            weight: { type: "number" },
+            title: { type: "string" },
+          },
+          required: ["weight", "title"],
+        },
+        handler: jest.fn(),
+      });
+
+      try {
+        // Mock getRestrictedParameters to return restricted params (would strip if called)
+        ToolAvailability.getRestrictedParameters.mockReturnValue(["weight"]);
+
+        // Make ConnectionManager throw (simulating uninitialized connection)
+        ConnectionManager.getInstance.mockReturnValue({
+          getInstanceInfo: jest.fn().mockImplementation(() => {
+            throw new Error("Connection not initialized");
+          }),
+        });
+
+        // Clear call history from beforeEach cache build before creating new instance
+        ToolAvailability.getRestrictedParameters.mockClear();
+
+        (RegistryManager as any).instance = null;
+        registryManager = RegistryManager.getInstance();
+
+        const tool = registryManager.getTool("tool_with_params");
+        expect(tool).toBeDefined();
+
+        const schema = tool?.inputSchema as any;
+
+        // Parameters should NOT be stripped when connection is unavailable
+        // (getRestrictedParameters should not be called at all)
+        expect(schema.properties?.weight).toBeDefined();
+        expect(schema.properties?.title).toBeDefined();
+        expect(schema.required).toContain("weight");
+
+        // Verify getRestrictedParameters was NOT called (guard prevented it)
+        expect(ToolAvailability.getRestrictedParameters).not.toHaveBeenCalled();
+      } finally {
+        coreRegistry.delete("tool_with_params");
+        ToolAvailability.getRestrictedParameters.mockReturnValue([]);
+        // Restore ConnectionManager mock
+        ConnectionManager.getInstance.mockReturnValue({
+          getInstanceInfo: jest.fn().mockReturnValue({ tier: "free", version: "17.0.0" }),
+        });
+      }
+    });
   });
 
   describe("Description Overrides", () => {