fix: improved error reporting; codex cli would at times fail to figure out how to handle plain-text / JSON errors

fix: working directory should exist, raise error and not try and create one
docs: improved API Lookup instructions
* test added to confirm failures
* chat schema more explicit about file paths

tools/workflow/workflow_mixin.py

@@ -33,6 +33,7 @@ from config import MCP_PROMPT_SIZE_LIMIT
 from utils.conversation_memory import add_turn, create_thread
 
 from ..shared.base_models import ConsolidatedFindings
+from ..shared.exceptions import ToolExecutionError
 
 logger = logging.getLogger(__name__)
 
@@ -645,7 +646,8 @@ class BaseWorkflowMixin(ABC):
                         content=path_error,
                         content_type="text",
                     )
-                    return [TextContent(type="text", text=error_output.model_dump_json())]
+                    logger.error("Path validation failed for %s: %s", self.get_name(), path_error)
+                    raise ToolExecutionError(error_output.model_dump_json())
             except AttributeError:
                 # validate_file_paths method not available - skip validation
                 pass
@@ -738,7 +740,13 @@ class BaseWorkflowMixin(ABC):
 
             return [TextContent(type="text", text=json.dumps(response_data, indent=2, ensure_ascii=False))]
 
+        except ToolExecutionError:
+            raise
         except Exception as e:
+            if str(e).startswith("MCP_SIZE_CHECK:"):
+                payload = str(e)[len("MCP_SIZE_CHECK:") :]
+                raise ToolExecutionError(payload)
+
             logger.error(f"Error in {self.get_name()} work: {e}", exc_info=True)
             error_data = {
                 "status": f"{self.get_name()}_failed",
@@ -749,7 +757,7 @@ class BaseWorkflowMixin(ABC):
             # Add metadata to error responses too
             self._add_workflow_metadata(error_data, arguments)
 
-            return [TextContent(type="text", text=json.dumps(error_data, indent=2, ensure_ascii=False))]
+            raise ToolExecutionError(json.dumps(error_data, indent=2, ensure_ascii=False)) from e
 
     # Hook methods for tool customization
 
@@ -1577,11 +1585,13 @@ class BaseWorkflowMixin(ABC):
                 error_data = {"status": "error", "content": "No arguments provided"}
                 # Add basic metadata even for validation errors
                 error_data["metadata"] = {"tool_name": self.get_name()}
-                return [TextContent(type="text", text=json.dumps(error_data, ensure_ascii=False))]
+                raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False))
 
             # Delegate to execute_workflow
             return await self.execute_workflow(arguments)
 
+        except ToolExecutionError:
+            raise
         except Exception as e:
             logger.error(f"Error in {self.get_name()} tool execution: {e}", exc_info=True)
             error_data = {
@@ -1589,12 +1599,7 @@ class BaseWorkflowMixin(ABC):
                 "content": f"Error in {self.get_name()}: {str(e)}",
             }  # Add metadata to error responses
             self._add_workflow_metadata(error_data, arguments)
-            return [
-                TextContent(
-                    type="text",
-                    text=json.dumps(error_data, ensure_ascii=False),
-                )
-            ]
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from e
 
     # Default implementations for methods that workflow-based tools typically don't need