fix(next-steps): Use tool-provided params over arg placeholders

Stop resolving manifest next-step params from raw invocation args and rely on tool-provided nextStepParams for canonical runtime values. Replace YAML arg placeholders with static defaults and update snapshot_ui to return dynamic params for all templated follow-up actions.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

manifests/tools/boot_sim.yaml

@@ -14,12 +14,12 @@ nextSteps:
   - label: Install an app
     toolId: install_app_sim
     params:
-      simulatorId: ${simulatorId}
+      simulatorId: SIMULATOR_UUID
       appPath: PATH_TO_YOUR_APP
     priority: 2
   - label: Launch an app
     toolId: launch_app_sim
     params:
-      simulatorId: ${simulatorId}
+      simulatorId: SIMULATOR_UUID
       bundleId: YOUR_APP_BUNDLE_ID
     priority: 3

manifests/tools/launch_app_sim.yaml

@@ -14,13 +14,13 @@ nextSteps:
   - label: Capture structured logs (app continues running)
     toolId: start_sim_log_cap
     params:
-      simulatorId: ${simulatorId}
-      bundleId: ${bundleId}
+      simulatorId: SIMULATOR_UUID
+      bundleId: BUNDLE_ID
     priority: 2
   - label: Capture console + structured logs (app restarts)
     toolId: start_sim_log_cap
     params:
-      simulatorId: ${simulatorId}
-      bundleId: ${bundleId}
+      simulatorId: SIMULATOR_UUID
+      bundleId: BUNDLE_ID
       captureConsole: true
     priority: 3

manifests/tools/snapshot_ui.yaml

@@ -8,17 +8,17 @@ nextSteps:
   - label: Refresh after layout changes
     toolId: snapshot_ui
     params:
-      simulatorId: ${simulatorId}
+      simulatorId: SIMULATOR_UUID
   - label: Tap on element
     toolId: tap
     params:
-      simulatorId: ${simulatorId}
+      simulatorId: SIMULATOR_UUID
       x: 0
       y: 0
   - label: Take screenshot for verification
     toolId: screenshot
     params:
-      simulatorId: ${simulatorId}
+      simulatorId: SIMULATOR_UUID
 annotations:
   title: Snapshot UI
   readOnlyHint: true

src/mcp/tools/ui-automation/__tests__/snapshot_ui.test.ts

@@ -102,6 +102,11 @@ describe('Snapshot UI Plugin', () => {
             text: 'Tips:\n- Use frame coordinates for tap/swipe (center: x+width/2, y+height/2)\n- If a debugger is attached, ensure the app is running (not stopped on breakpoints)\n- Screenshots are for visual verification only',
           },
         ],
+        nextStepParams: {
+          snapshot_ui: { simulatorId: '12345678-1234-4234-8234-123456789012' },
+          tap: { simulatorId: '12345678-1234-4234-8234-123456789012', x: 0, y: 0 },
+          screenshot: { simulatorId: '12345678-1234-4234-8234-123456789012' },
+        },
       });
     });
 

src/mcp/tools/ui-automation/snapshot_ui.ts

@@ -86,6 +86,11 @@ export async function snapshot_uiLogic(
           text: `Tips:\n- Use frame coordinates for tap/swipe (center: x+width/2, y+height/2)\n- If a debugger is attached, ensure the app is running (not stopped on breakpoints)\n- Screenshots are for visual verification only`,
         },
       ],
+      nextStepParams: {
+        snapshot_ui: { simulatorId },
+        tap: { simulatorId, x: 0, y: 0 },
+        screenshot: { simulatorId },
+      },
     };
     if (guard.warningText) {
       response.content.push({ type: 'text', text: guard.warningText });

src/runtime/__tests__/tool-invoker.test.ts

@@ -252,8 +252,14 @@ describe('DefaultToolInvoker next steps post-processing', () => {
     ]);
   });
 
-  it('injects manifest template next steps when a response omits nextSteps', async () => {
-    const directHandler = vi.fn().mockResolvedValue(textResponse('ok'));
+  it('injects manifest template next steps from dynamic nextStepParams when response omits nextSteps', async () => {
+    const directHandler = vi.fn().mockResolvedValue({
+      content: [{ type: 'text', text: 'ok' }],
+      nextStepParams: {
+        snapshot_ui: { simulatorId: '12345678-1234-4234-8234-123456789012' },
+        tap: { simulatorId: '12345678-1234-4234-8234-123456789012', x: 0, y: 0 },
+      },
+    } satisfies ToolResponse);
     const catalog = createToolCatalog([
       makeTool({
         id: 'snapshot_ui',
@@ -265,15 +271,15 @@ describe('DefaultToolInvoker next steps post-processing', () => {
           {
             label: 'Refresh',
             toolId: 'snapshot_ui',
-            params: { simulatorId: '${simulatorId}' },
+            params: { simulatorId: 'SIMULATOR_UUID' },
           },
           {
             label: 'Visually verify hierarchy output',
           },
           {
             label: 'Tap on element',
             toolId: 'tap',
-            params: { simulatorId: '${simulatorId}', x: 0, y: 0 },
+            params: { simulatorId: 'SIMULATOR_UUID', x: 0, y: 0 },
           },
         ],
         handler: directHandler,
@@ -289,11 +295,7 @@ describe('DefaultToolInvoker next steps post-processing', () => {
     ]);
 
     const invoker = new DefaultToolInvoker(catalog);
-    const response = await invoker.invoke(
-      'snapshot-ui',
-      { simulatorId: '12345678-1234-4234-8234-123456789012' },
-      { runtime: 'cli' },
-    );
+    const response = await invoker.invoke('snapshot-ui', {}, { runtime: 'cli' });
 
     expect(response.nextSteps).toEqual([
       {

src/runtime/tool-invoker.ts

@@ -12,45 +12,13 @@ import {
   type SentryToolTransport,
 } from '../utils/sentry.ts';
 
-/**
- * Resolve template params using input args.
- * Supports primitive passthrough and ${argName} substitution.
- */
-function resolveTemplateParams(
-  params: Record<string, string | number | boolean>,
-  args: Record<string, unknown>,
-): Record<string, string | number | boolean> {
-  const resolved: Record<string, string | number | boolean> = {};
-
-  for (const [key, value] of Object.entries(params)) {
-    if (typeof value === 'string') {
-      const match = value.match(/^\$\{([^}]+)\}$/);
-      if (match) {
-        const argValue = args[match[1]];
-        if (
-          typeof argValue === 'string' ||
-          typeof argValue === 'number' ||
-          typeof argValue === 'boolean'
-        ) {
-          resolved[key] = argValue;
-          continue;
-        }
-      }
-    }
-    resolved[key] = value;
-  }
-
-  return resolved;
-}
-
 type BuiltTemplateNextStep = {
   step: NextStep;
   templateToolId?: string;
 };
 
 function buildTemplateNextSteps(
   tool: ToolDefinition,
-  args: Record<string, unknown>,
   catalog: ToolCatalog,
 ): BuiltTemplateNextStep[] {
   if (!tool.nextStepTemplates || tool.nextStepTemplates.length === 0) {
@@ -78,7 +46,7 @@ function buildTemplateNextSteps(
       step: {
         tool: target.mcpName,
         label: template.label,
-        params: resolveTemplateParams(template.params ?? {}, args),
+        params: template.params ?? {},
         priority: template.priority,
       },
       templateToolId: template.toolId,
@@ -194,13 +162,12 @@ function normalizeNextSteps(
 export function postProcessToolResponse(params: {
   tool: ToolDefinition;
   response: ToolResponse;
-  args: Record<string, unknown>;
   catalog: ToolCatalog;
   runtime: InvokeOptions['runtime'];
 }): ToolResponse {
-  const { tool, response, args, catalog, runtime } = params;
+  const { tool, response, catalog, runtime } = params;
 
-  const templateSteps = buildTemplateNextSteps(tool, args, catalog);
+  const templateSteps = buildTemplateNextSteps(tool, catalog);
   const canApplyTemplates =
     templateSteps.length > 0 &&
     (!response.nextSteps ||
@@ -292,15 +259,13 @@ export class DefaultToolInvoker implements ToolInvoker {
 
   private buildPostProcessParams(
     tool: ToolDefinition,
-    args: Record<string, unknown>,
     runtime: InvokeOptions['runtime'],
   ): {
     tool: ToolDefinition;
-    args: Record<string, unknown>;
     catalog: ToolCatalog;
     runtime: InvokeOptions['runtime'];
   } {
-    return { tool, args, catalog: this.catalog, runtime };
+    return { tool, catalog: this.catalog, runtime };
   }
 
   private async invokeViaDaemon(
@@ -313,7 +278,6 @@ export class DefaultToolInvoker implements ToolInvoker {
       captureInvocationMetric: (outcome: SentryToolInvocationOutcome) => void;
       postProcessParams: {
         tool: ToolDefinition;
-        args: Record<string, unknown>;
         catalog: ToolCatalog;
         runtime: InvokeOptions['runtime'];
       };
@@ -407,7 +371,7 @@ export class DefaultToolInvoker implements ToolInvoker {
       });
     };
 
-    const postProcessParams = this.buildPostProcessParams(tool, args, opts.runtime);
+    const postProcessParams = this.buildPostProcessParams(tool, opts.runtime);
     const xcodeIdeRemoteToolName = tool.xcodeIdeRemoteToolName;
     const isDynamicXcodeIdeTool =
       tool.workflow === 'xcode-ide' && typeof xcodeIdeRemoteToolName === 'string';

src/utils/tool-registry.ts

@@ -148,7 +148,6 @@ export async function applyWorkflowSelectionFromManifest(
                   ? postProcessToolResponse({
                       tool: catalogTool,
                       response: response as ToolResponse,
-                      args: args as Record<string, unknown>,
                       catalog,
                       runtime: 'mcp',
                     })