@falai/agent 1.2.8 → 2.0.0

package/dist/core/ToolManager.js

@@ -33,8 +33,53 @@ export class ToolExecutionError extends Error {
 export class ToolManager {
     constructor(agent) {
         this.agent = agent;
+        /**
+         * Per-turn transient tool layer populated from PreDirective.injectTools.
+         * Resolution order: transient → step → flow → agent.
+         * Drained at end of turn via try/finally guard.
+         *
+         * Tools are deduplicated by `id` with last-definition-wins when
+         * multiple pre-LLM emitters contribute tools in the same turn.
+         */
+        this.transientTools = new Map();
         this.toolRegistry = new Map();
     }
+    /**
+     * Set the transient tool layer for the current turn.
+     *
+     * Accepts the merged `injectTools` array from pre-LLM emitters
+     * (already concatenated in outer-to-inner order by the DirectiveBus).
+     * Deduplicates by tool `id` with last-definition-wins.
+     *
+     * Must be paired with `clearTransientTools()` in a try/finally guard
+     * so the layer is drained even on abnormal termination.
+     */
+    setTransientTools(tools) {
+        this.transientTools.clear();
+        for (const tool of tools) {
+            this.transientTools.set(tool.id, tool);
+        }
+        if (this.transientTools.size > 0) {
+            logger.debug(`[ToolManager] Set transient tools for turn: ${Array.from(this.transientTools.keys()).join(', ')}`);
+        }
+    }
+    /**
+     * Clear the transient tool layer. Called at end of turn via try/finally
+     * guard so tools do not leak into subsequent turns.
+     */
+    clearTransientTools() {
+        if (this.transientTools.size > 0) {
+            logger.debug(`[ToolManager] Cleared transient tools: ${Array.from(this.transientTools.keys()).join(', ')}`);
+        }
+        this.transientTools.clear();
+    }
+    /**
+     * Check whether the transient layer currently has any tools.
+     * Useful for testing and debugging.
+     */
+    hasTransientTools() {
+        return this.transientTools.size > 0;
+    }
     /**
      * Validate a tool definition for completeness and correctness
      */
@@ -53,10 +98,6 @@ export class ToolManager {
         if (!definition.handler || typeof definition.handler !== 'function') {
             errors.push('Tool handler is required and must be a function');
         }
-        // Optional fields validation
-        if (definition.name !== undefined && (typeof definition.name !== 'string' || definition.name.trim() === '')) {
-            errors.push('Tool name must be a non-empty string if provided');
-        }
         if (definition.description !== undefined && (typeof definition.description !== 'string' || definition.description.trim() === '')) {
             errors.push('Tool description must be a non-empty string if provided');
         }
@@ -82,7 +123,8 @@ export class ToolManager {
             }
         }
         if (errors.length > 0) {
-            throw new ToolCreationError(`Tool definition validation failed: ${errors.join('; ')}`, definition.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] Tool definition validation failed for "${definition.id || 'unknown'}": ${errors.join('; ')}. ` +
+                `Fix the tool definition to meet the required schema.`, definition.id || 'unknown');
         }
     }
     /**
@@ -97,7 +139,8 @@ export class ToolManager {
             errors.push('Data enrichment enricher must be a function');
         }
         if (errors.length > 0) {
-            throw new ToolCreationError(`Data enrichment configuration validation failed: ${errors.join('; ')}`, config.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] Data enrichment config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
+                `Fix the enrichment config to satisfy the required fields.`, config.id || 'unknown');
         }
     }
     /**
@@ -112,7 +155,8 @@ export class ToolManager {
             errors.push('Validation validator must be a function');
         }
         if (errors.length > 0) {
-            throw new ToolCreationError(`Validation configuration validation failed: ${errors.join('; ')}`, config.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] Validation config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
+                `Fix the validation config to satisfy the required fields.`, config.id || 'unknown');
         }
     }
     /**
@@ -139,7 +183,8 @@ export class ToolManager {
             errors.push('API call transform must be a function');
         }
         if (errors.length > 0) {
-            throw new ToolCreationError(`API call configuration validation failed: ${errors.join('; ')}`, config.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] API call config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
+                `Fix the API call config to satisfy the required fields.`, config.id || 'unknown');
         }
     }
     /**
@@ -154,7 +199,8 @@ export class ToolManager {
             errors.push('Computation compute function is required');
         }
         if (errors.length > 0) {
-            throw new ToolCreationError(`Computation configuration validation failed: ${errors.join('; ')}`, config.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] Computation config validation failed for "${config.id || 'unknown'}": ${errors.join('; ')}. ` +
+                `Fix the computation config to satisfy the required fields.`, config.id || 'unknown');
         }
     }
     /**
@@ -169,7 +215,8 @@ export class ToolManager {
             return definition;
         }
         catch (error) {
-            throw new ToolCreationError(`Failed to create tool '${definition.id}': ${error instanceof Error ? error.message : String(error)}`, definition.id, error instanceof Error ? error : undefined);
+            throw new ToolCreationError(`[ToolCreationError] Failed to create tool "${definition.id}": ${error instanceof Error ? error.message : String(error)}. ` +
+                `Ensure the tool definition passes validation.`, definition.id, error instanceof Error ? error : undefined);
         }
     }
     /**
@@ -179,22 +226,22 @@ export class ToolManager {
     register(tool) {
         try {
             if (!tool) {
-                throw new ToolCreationError('Tool is required for registration', 'unknown');
+                throw new ToolCreationError('[ToolCreationError] Tool registration failed: no tool provided. Pass a valid tool object with id and handler.', 'unknown');
             }
             if (!('handler' in tool) || typeof tool.handler !== 'function') {
-                throw new ToolCreationError('Invalid tool provided for registration - must have a handler function', tool?.id || 'unknown');
+                throw new ToolCreationError(`[ToolCreationError] Invalid tool for registration: tool "${tool?.id || 'unknown'}" must have a handler function. Add a handler property.`, tool?.id || 'unknown');
             }
             // Validate the tool
             if (!tool.id || typeof tool.id !== 'string' || tool.id.trim() === '') {
-                throw new ToolCreationError('Tool ID is required and must be a non-empty string', tool.id || 'unknown');
+                throw new ToolCreationError('[ToolCreationError] Tool ID missing: tool ID is required and must be a non-empty string. Provide a unique string id.', tool.id || 'unknown');
             }
             // Check for ID conflicts and provide better error context
             if (this.toolRegistry.has(tool.id)) {
                 const existingTool = this.toolRegistry.get(tool.id);
-                logger.warn(`[ToolManager] Overwriting existing registered tool: ${tool.id} (previous: ${existingTool?.name || 'unnamed'})`);
+                logger.warn(`[ToolManager] Overwriting existing registered tool: ${tool.id} (previous: ${existingTool?.id || 'unnamed'})`);
             }
             this.toolRegistry.set(tool.id, tool);
-            logger.debug(`[ToolManager] Registered tool: ${tool.id} (${tool.name || 'unnamed'})`);
+            logger.debug(`[ToolManager] Registered tool: ${tool.id} (${tool.id || 'unnamed'})`);
             return tool;
         }
         catch (error) {
@@ -202,7 +249,8 @@ export class ToolManager {
                 throw error;
             }
             const toolId = tool?.id || 'unknown';
-            throw new ToolCreationError(`Failed to register tool '${toolId}': ${error instanceof Error ? error.message : String(error)}`, toolId, error instanceof Error ? error : undefined);
+            throw new ToolCreationError(`[ToolCreationError] Failed to register tool "${toolId}": ${error instanceof Error ? error.message : String(error)}. ` +
+                `Ensure the tool object is valid and has id + handler.`, toolId, error instanceof Error ? error : undefined);
         }
     }
     /**
@@ -238,20 +286,20 @@ export class ToolManager {
     /**
      * Get tool by ID from a specific scope
      */
-    getFromScope(toolId, scope, step, route) {
-        return this.find(toolId, scope, step, route);
+    getFromScope(toolId, scope, step, flow) {
+        return this.find(toolId, scope, step, flow);
     }
     /**
      * Check if a tool exists in any scope
      */
-    exists(toolId, step, route) {
-        return this.find(toolId, ToolScope.ALL, step, route) !== undefined;
+    exists(toolId, step, flow) {
+        return this.find(toolId, ToolScope.ALL, step, flow) !== undefined;
     }
     /**
      * Get tool count by scope
      */
-    getToolCount(scope, step, route) {
-        return this.getAvailable(scope, step, route).length;
+    getToolCount(scope, step, flow) {
+        return this.getAvailable(scope, step, flow).length;
     }
     /**
      * Clear all registered tools
@@ -277,7 +325,8 @@ export class ToolManager {
     addToAgent(tool) {
         // Validate tool before adding
         if (!tool || !tool.id || !tool.handler) {
-            throw new ToolCreationError('Invalid tool: must have id and handler properties', tool?.id || 'unknown');
+            throw new ToolCreationError(`[ToolCreationError] Invalid tool for addToAgent: tool must have id and handler properties. ` +
+                `Provide a complete tool object with { id, handler, ... }.`, tool?.id || 'unknown');
         }
         // Add to agent's tools array using the unified interface
         if (this.agent) {
@@ -290,33 +339,41 @@ export class ToolManager {
         return tool;
     }
     /**
-     * Add a tool to a specific route scope (creates and adds in one operation)
+     * Add a tool to a specific flow scope (creates and adds in one operation)
      */
-    addToRoute(route, tool) {
-        // Add to route's tools array using the existing createTool method
-        if (route && typeof route.createTool === 'function') {
-            route.createTool(tool);
+    addToFlow(flow, tool) {
+        // Add to flow's tools array using the existing createTool method
+        if (flow && typeof flow.createTool === 'function') {
+            flow.createTool(tool);
         }
         else {
-            logger.warn(`[ToolManager] Route does not support createTool method, tool not added to route scope: ${tool.id}`);
+            logger.warn(`[ToolManager] Flow does not support createTool method, tool not added to flow scope: ${tool.id}`);
         }
-        logger.debug(`[ToolManager] Added tool to route scope: ${tool.id}`);
+        logger.debug(`[ToolManager] Added tool to flow scope: ${tool.id}`);
         return tool;
     }
     /**
      * Find a tool by ID across different scopes with enhanced resolution logic
-     * Priority: step → route → agent → registry
+     * Priority: transient → step → flow → agent → registry
      * Supports both ID and name matching for better compatibility
      */
-    find(toolId, scope, step, route) {
+    find(toolId, scope, step, flow) {
         logger.debug(`[ToolManager] Finding tool: ${toolId} with scope: ${scope || 'ALL'}`);
-        // Check step-level tools first (if step provided and scope allows)
+        // Check transient tools first (highest priority — per-turn injectTools)
+        if (!scope || scope === ToolScope.ALL) {
+            const transientTool = this.transientTools.get(toolId);
+            if (transientTool) {
+                logger.debug(`[ToolManager] Found tool in transient scope: ${toolId}`);
+                return transientTool;
+            }
+        }
+        // Check step-level tools (if step provided and scope allows)
         if (step && (!scope || scope === ToolScope.STEP || scope === ToolScope.ALL)) {
             if (step.tools) {
                 for (const toolRef of step.tools) {
                     if (typeof toolRef !== 'string') {
                         // Inline tool object - check both id and name
-                        if (toolRef.id === toolId || toolRef.name === toolId) {
+                        if (toolRef.id === toolId) {
                             logger.debug(`[ToolManager] Found tool in step scope: ${toolId}`);
                             return toolRef;
                         }
@@ -334,13 +391,13 @@ export class ToolManager {
                 }
             }
         }
-        // Check route-level tools (if route provided and scope allows)
-        if (route && (!scope || scope === ToolScope.ROUTE || scope === ToolScope.ALL)) {
-            if (route.tools) {
-                const routeTool = route.tools.find((t) => t.id === toolId || t.name === toolId);
-                if (routeTool) {
-                    logger.debug(`[ToolManager] Found tool in route scope: ${toolId}`);
-                    return routeTool;
+        // Check flow-level tools (if route provided and scope allows)
+        if (flow && (!scope || scope === ToolScope.FLOW || scope === ToolScope.ALL)) {
+            if (flow.tools) {
+                const flowTool = flow.tools.find((t) => t.id === toolId);
+                if (flowTool) {
+                    logger.debug(`[ToolManager] Found tool in flow scope: ${toolId}`);
+                    return flowTool;
                 }
             }
         }
@@ -348,7 +405,7 @@ export class ToolManager {
         if (!scope || scope === ToolScope.AGENT || scope === ToolScope.ALL) {
             if (this.agent) {
                 const agentTools = this.agent.getTools();
-                const agentTool = agentTools.find((t) => t.id === toolId || t.name === toolId);
+                const agentTool = agentTools.find((t) => t.id === toolId);
                 if (agentTool) {
                     logger.debug(`[ToolManager] Found tool in agent scope: ${toolId}`);
                     return agentTool;
@@ -364,7 +421,7 @@ export class ToolManager {
             }
             // Also check by name in registry
             for (const [id, tool] of Array.from(this.toolRegistry.entries())) {
-                if (tool.name === toolId) {
+                if (tool.id === toolId) {
                     logger.debug(`[ToolManager] Found tool in registry by name: ${toolId} (id: ${id})`);
                     return tool;
                 }
@@ -376,8 +433,9 @@ export class ToolManager {
     /**
      * Get available tools for current context with enhanced resolution and deduplication
      * Returns tools in priority order with higher-priority scopes taking precedence
+     * Resolution order: transient → step → flow → agent → registry
      */
-    getAvailable(scope, step, route) {
+    getAvailable(scope, step, flow) {
         const toolMap = new Map();
         const resolvedTools = [];
         logger.debug(`[ToolManager] Getting available tools with scope: ${scope || 'ALL'}`);
@@ -399,15 +457,15 @@ export class ToolManager {
             }
         }
         // Add route-level tools (override agent and registered tools with same ID)
-        if (route && (!scope || scope === ToolScope.ROUTE || scope === ToolScope.ALL)) {
-            if (route.tools) {
-                for (const tool of route.tools) {
+        if (flow && (!scope || scope === ToolScope.FLOW || scope === ToolScope.ALL)) {
+            if (flow.tools) {
+                for (const tool of flow.tools) {
                     toolMap.set(tool.id, tool);
                 }
-                logger.debug(`[ToolManager] Added ${route.tools.length} route tools`);
+                logger.debug(`[ToolManager] Added ${flow.tools.length} flow.tools`);
             }
         }
-        // Add step-level tools (highest priority - override all others with same ID)
+        // Add step-level tools (override flow/agent/registry with same ID)
         if (step && (!scope || scope === ToolScope.STEP || scope === ToolScope.ALL)) {
             if (step.tools) {
                 for (const toolRef of step.tools) {
@@ -424,21 +482,33 @@ export class ToolManager {
                             resolvedTools.push(registeredTool);
                         }
                         else {
-                            logger.warn(`[ToolManager] Step references unknown tool: ${toolRef}`);
+                            logger.warn(`[ToolExecutionError] Step references unknown tool: "${toolRef}" is not registered. Skipping. Register the tool or remove the reference.`);
                         }
                     }
                 }
                 logger.debug(`[ToolManager] Added ${step.tools.length} step tools (${resolvedTools.length} resolved)`);
             }
         }
+        // Add transient tools (highest priority — override everything with same ID)
+        if (!scope || scope === ToolScope.ALL) {
+            if (this.transientTools.size > 0) {
+                for (const [id, tool] of this.transientTools) {
+                    toolMap.set(id, tool);
+                }
+                logger.debug(`[ToolManager] Added ${this.transientTools.size} transient tools`);
+            }
+        }
         // Convert map to array, preserving priority order
         const allTools = Array.from(toolMap.values());
-        // If we have step-specific tools, prioritize them
+        // If we have step-specific tools, prioritize them in the ordering
+        // (but transient tools that override step tools via same ID are already in the map)
         if (resolvedTools.length > 0) {
             // Add resolved step tools first, then other tools not already included
             const stepToolIds = new Set(resolvedTools.map(t => t.id));
             const otherTools = allTools.filter(t => !stepToolIds.has(t.id));
-            return [...resolvedTools, ...otherTools];
+            // For step tools, use the map version (which may be overridden by transient)
+            const finalStepTools = resolvedTools.map(t => toolMap.get(t.id) || t);
+            return [...finalStepTools, ...otherTools];
         }
         logger.debug(`[ToolManager] Returning ${allTools.length} available tools`);
         return allTools;
@@ -462,7 +532,7 @@ export class ToolManager {
         // Try primary tool with retries
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
-                const tool = this.find(toolId, undefined, context?.step, context?.route);
+                const tool = this.find(toolId, undefined, context?.step, context?.flow);
                 if (!tool) {
                     // Tool not found - try fallback tools if available
                     if (fallbackTools.length > 0) {
@@ -574,7 +644,8 @@ export class ToolManager {
             }
         }
         // All attempts and fallbacks failed
-        throw new ToolExecutionError(`Tool execution failed after ${maxRetries + 1} attempts: ${lastError?.message || 'Unknown error'}${fallbackTools.length > 0 ? ` (fallback tools also failed: ${fallbackTools.join(', ')})` : ''}`, toolId, { args, context, attempts: maxRetries + 1, fallbackTools }, lastError);
+        throw new ToolExecutionError(`[ToolExecutionError] Tool "${toolId}" execution failed: all ${maxRetries + 1} attempts exhausted${fallbackTools.length > 0 ? ` and fallback tools [${fallbackTools.join(', ')}] also failed` : ''}. ` +
+            `Check the tool handler for errors or increase maxRetries. Last error: ${lastError?.message || 'Unknown'}.`, toolId, { args, context, attempts: maxRetries + 1, fallbackTools }, lastError);
     }
     /**
      * Determine if an error is transient and should be retried
@@ -612,6 +683,7 @@ export class ToolManager {
                 };
             }
             // Build tool context with complete agent data
+            const collectedDirectives = [];
             const toolContext = {
                 context,
                 updateContext,
@@ -628,16 +700,18 @@ export class ToolManager {
                 },
                 hasField: (key) => {
                     return data != null && key in data;
+                },
+                dispatch: (directive) => {
+                    collectedDirectives.push(directive);
                 }
             };
             logger.debug(`[ToolManager] Executing tool: ${tool.id} with args:`, toolArguments);
-            // EnhancedTool validation gate (Req 9.2, 10.6)
-            const enhanced = tool;
-            if (typeof enhanced.validateInput === 'function' && toolArguments) {
-                const validation = await enhanced.validateInput(toolArguments, toolContext);
+            // Tool validation gate (Req 6.1, 6.7)
+            if (typeof tool.validateInput === 'function' && toolArguments) {
+                const validation = await tool.validateInput(toolArguments, toolContext);
                 if (!validation.valid) {
                     const executionTime = Date.now() - startTime;
-                    logger.warn(`[ToolManager] Tool ${tool.id} input validation failed: ${validation.error}`);
+                    logger.warn(`[DataValidationError] Tool "${tool.id}" input validation failed: ${validation.error}. Fix the tool call arguments to match the expected schema.`);
                     return {
                         success: false,
                         error: `Validation failed: ${validation.error || 'Invalid input'}`,
@@ -645,12 +719,13 @@ export class ToolManager {
                     };
                 }
             }
-            // EnhancedTool permission gate (Req 9.3, 10.6)
-            if (typeof enhanced.checkPermissions === 'function' && toolArguments) {
-                const permission = await enhanced.checkPermissions(toolArguments, toolContext);
+            // Tool permission gate (Req 6.7, 6.8)
+            // When denied: do not invoke handler, do not process directives, do not apply state writes
+            if (typeof tool.checkPermissions === 'function' && toolArguments) {
+                const permission = await tool.checkPermissions(toolArguments, toolContext);
                 if (!permission.allowed) {
                     const executionTime = Date.now() - startTime;
-                    logger.warn(`[ToolManager] Tool ${tool.id} permission denied: ${permission.reason}`);
+                    logger.warn(`[ToolExecutionError] Tool "${tool.id}" permission denied: ${permission.reason}. The tool's checkPermissions hook rejected this call.`);
                     return {
                         success: false,
                         error: `Permission denied: ${permission.reason || 'Not allowed'}`,
@@ -676,7 +751,7 @@ export class ToolManager {
             logger.debug(`[ToolManager] Tool ${tool.id} completed in ${executionTime}ms`);
             // Handle different result types
             let toolResult;
-            if (result && typeof result === 'object' && ('data' in result || 'success' in result || 'error' in result)) {
+            if (result && typeof result === 'object' && ('data' in result || 'success' in result || 'error' in result || 'directive' in result)) {
                 // It's already a ToolResult-like object
                 toolResult = result;
             }
@@ -687,6 +762,10 @@ export class ToolManager {
                     success: true
                 };
             }
+            // Collect directive from ToolResult.directive (if present)
+            if (toolResult.directive) {
+                collectedDirectives.push(toolResult.directive);
+            }
             // Apply data updates from tool result with validation
             if (toolResult.dataUpdate) {
                 try {
@@ -694,7 +773,7 @@ export class ToolManager {
                         await updateData(toolResult.dataUpdate);
                     }
                     else {
-                        logger.warn(`[ToolManager] Tool ${tool.id} returned invalid dataUpdate: expected object, got ${typeof toolResult.dataUpdate}`);
+                        logger.warn(`[DataValidationError] Tool "${tool.id}" returned invalid dataUpdate: expected object, got ${typeof toolResult.dataUpdate}. Fix the tool handler to return a valid dataUpdate object.`);
                     }
                 }
                 catch (updateError) {
@@ -713,7 +792,7 @@ export class ToolManager {
                         await updateContext(toolResult.contextUpdate);
                     }
                     else {
-                        logger.warn(`[ToolManager] Tool ${tool.id} returned invalid contextUpdate: expected object, got ${typeof toolResult.contextUpdate}`);
+                        logger.warn(`[DataValidationError] Tool "${tool.id}" returned invalid contextUpdate: expected object, got ${typeof toolResult.contextUpdate}. Fix the tool handler to return a valid contextUpdate object.`);
                     }
                 }
                 catch (updateError) {
@@ -732,9 +811,10 @@ export class ToolManager {
                 contextUpdate: toolResult.contextUpdate,
                 dataUpdate: toolResult.dataUpdate,
                 error: toolResult.error,
+                directives: collectedDirectives.length > 0 ? collectedDirectives : undefined,
                 metadata: {
                     toolId: tool.id,
-                    toolName: tool.name,
+                    toolName: tool.id,
                     executionTime,
                     ...(toolResult.meta || {})
                 }
@@ -789,7 +869,7 @@ export class ToolManager {
      * Progress messages are yielded immediately.
      */
     async *executeWithConcurrency(params) {
-        const { toolCalls, context, data, history, signal, route, step } = params;
+        const { toolCalls, context, data, history, signal, flow, step } = params;
         if (toolCalls.length === 0) {
             return;
         }
@@ -798,7 +878,7 @@ export class ToolManager {
             context,
             data: data || {},
             history: history || [],
-            step: step ? { id: step.id, routeId: route?.id || '' } : undefined,
+            step: step ? { id: step.id, flowId: flow?.id || '' } : undefined,
             updateContext: (updates) => {
                 Object.assign(context, updates);
                 return Promise.resolve();
@@ -821,18 +901,23 @@ export class ToolManager {
             hasField: (key) => {
                 return data != null && key in data;
             },
+            dispatch: (_directive) => {
+                // Directives from concurrent execution are collected by the StreamingToolExecutor
+                // and surfaced via ToolExecutionUpdate. This is a no-op placeholder;
+                // full directive bus integration happens in ResponsePipeline (task 1.6).
+            },
         };
         const executor = new StreamingToolExecutor(toolContext, {
             signal,
         });
         // Resolve and queue each tool call
         for (const toolCall of toolCalls) {
-            const tool = this.find(toolCall.toolName, undefined, step, route);
+            const tool = this.find(toolCall.toolName, undefined, step, flow);
             if (!tool) {
-                logger.warn(`[ToolManager] Tool not found for concurrent execution: ${toolCall.toolName}`);
+                logger.warn(`[ToolExecutionError] Tool not found for concurrent execution: "${toolCall.toolName}" is not registered in any scope. Skipping. Register the tool or check the tool name.`);
                 continue;
             }
-            // Cast to EnhancedTool — plain Tools are compatible (defaults apply)
+            // Tool carries all metadata fields directly — no cast needed
             executor.addTool(toolCall, tool);
         }
         // Yield all results in order
@@ -847,7 +932,6 @@ export class ToolManager {
         this.validateDataEnrichmentConfig(config);
         const tool = {
             id: config.id,
-            name: config.name || `Data Enrichment: ${config.id}`,
             description: config.description || `Enriches data fields: ${config.fields.join(', ')}`,
             parameters: {
                 type: 'object',
@@ -886,7 +970,8 @@ export class ToolManager {
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     logger.error(`[ToolManager] Data enrichment failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`Data enrichment failed: ${errorMessage}`, config.id, { fields: config.fields }, error instanceof Error ? error : undefined);
+                    throw new ToolExecutionError(`[ToolExecutionError] Data enrichment failed for tool "${config.id}": ${errorMessage}. ` +
+                        `Check the enrichment handler and field references.`, config.id, { fields: config.fields }, error instanceof Error ? error : undefined);
                 }
             }
         };
@@ -901,7 +986,6 @@ export class ToolManager {
         this.validateValidationConfig(config);
         const tool = {
             id: config.id,
-            name: config.name || `Validation: ${config.id}`,
             description: config.description || `Validates data fields: ${config.fields.join(', ')}`,
             parameters: {
                 type: 'object',
@@ -958,7 +1042,6 @@ export class ToolManager {
         this.validateApiCallConfig(config);
         const tool = {
             id: config.id,
-            name: config.name || `API Call: ${config.id}`,
             description: config.description || `Makes API call to external service`,
             parameters: {
                 type: 'object',
@@ -1019,7 +1102,8 @@ export class ToolManager {
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     logger.error(`[ToolManager] API call failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`API call failed: ${errorMessage}`, config.id, { endpoint: config.endpoint, method: config.method, args }, error instanceof Error ? error : undefined);
+                    throw new ToolExecutionError(`[ToolExecutionError] API call failed for tool "${config.id}": ${errorMessage}. ` +
+                        `Check the endpoint URL, method, and network connectivity.`, config.id, { endpoint: config.endpoint, method: config.method, args }, error instanceof Error ? error : undefined);
                 }
             }
         };
@@ -1034,7 +1118,6 @@ export class ToolManager {
         this.validateComputationConfig(config);
         const tool = {
             id: config.id,
-            name: config.name || `Computation: ${config.id}`,
             description: config.description || `Performs computation on inputs: ${config.inputs.join(', ')}`,
             parameters: {
                 type: 'object',
@@ -1066,7 +1149,8 @@ export class ToolManager {
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     logger.error(`[ToolManager] Computation failed for ${config.id}: ${errorMessage}`);
-                    throw new ToolExecutionError(`Computation failed: ${errorMessage}`, config.id, { inputs: config.inputs, args }, error instanceof Error ? error : undefined);
+                    throw new ToolExecutionError(`[ToolExecutionError] Computation failed for tool "${config.id}": ${errorMessage}. ` +
+                        `Check the compute function and input field references.`, config.id, { inputs: config.inputs, args }, error instanceof Error ? error : undefined);
                 }
             }
         };
@@ -1075,8 +1159,8 @@ export class ToolManager {
     /**
      * Get detailed information about a tool for debugging
      */
-    getToolInfo(toolId, scope, step, route) {
-        const tool = this.find(toolId, scope, step, route);
+    getToolInfo(toolId, scope, step, flow) {
+        const tool = this.find(toolId, scope, step, flow);
         if (!tool) {
             return { found: false };
         }
@@ -1085,20 +1169,20 @@ export class ToolManager {
         // Check step scope
         if (step?.tools) {
             const stepTool = step.tools.find((t) => (typeof t === 'string' && t === toolId) ||
-                (typeof t === 'object' && (t.id === toolId || t.name === toolId)));
+                (typeof t === 'object' && (t.id === toolId)));
             if (stepTool)
                 foundScope = 'step';
         }
         // Check route scope
-        if (foundScope === 'unknown' && route?.tools) {
-            const routeTool = route.tools.find((t) => t.id === toolId || t.name === toolId);
-            if (routeTool)
-                foundScope = 'route';
+        if (foundScope === 'unknown' && flow?.tools) {
+            const flowTool = flow.tools.find((t) => t.id === toolId);
+            if (flowTool)
+                foundScope = 'flow';
         }
         // Check agent scope
         if (foundScope === 'unknown' && this.agent) {
-            const agentTools = this.agent.getTools();
-            const agentTool = agentTools.find((t) => t.id === toolId || t.name === toolId);
+            const agentTools = this.agent.tools;
+            const agentTool = agentTools.find((t) => t.id === toolId);
             if (agentTool)
                 foundScope = 'agent';
         }
@@ -1112,7 +1196,6 @@ export class ToolManager {
             scope: foundScope,
             metadata: {
                 id: tool.id,
-                name: tool.name,
                 hasDescription: !!tool.description,
                 hasParameters: !!tool.parameters,
                 handlerLength: tool.handler.length
@@ -1122,12 +1205,12 @@ export class ToolManager {
     /**
      * Validate that all tools in a list exist and are accessible
      */
-    validateToolReferences(toolIds, step, route) {
+    validateToolReferences(toolIds, step, flow) {
         const missing = [];
         const found = [];
         const details = [];
         for (const toolId of toolIds) {
-            const info = this.getToolInfo(toolId, ToolScope.ALL, step, route);
+            const info = this.getToolInfo(toolId, ToolScope.ALL, step, flow);
             if (info.found) {
                 found.push(toolId);
                 details.push({ id: toolId, found: true, scope: info.scope });