# Function handleToolError

- handleToolError(error: unknown, toolName: string): ToolResult

  Handle a caught tool error, returning a safe MCP error response. Never exposes raw stack traces to MCP clients.

  Timeout handling: When the root cause is a request timeout (status 408 or `TimeoutError`), returns a structured non-error response with `data: []` and a `dataQualityWarnings` array instead of `isError: true`. This prevents MCP clients from retrying the same slow request.

  For non-timeout errors, the error is delegated to buildErrorResponse which auto-classifies via `classifyError()` and includes structured error classification metadata (errorCode, errorCategory, httpStatus) enabling programmatic retry logic. If the error is a ToolError, its own `toolName` is preserved. Retryability is determined by auto-classification (inspecting the cause chain) but can still honor `ToolError.isRetryable` in generic fallback cases when no more specific signal is available.

  #### Parameters

  - error: unknown

    Caught error value

  - toolName: string

    Fallback tool name when error carries no tool identity

  #### Returns ToolResult

  MCP-compliant ToolResult with isError flag set (or structured timeout response)

  - Defined in tools/shared/errorHandler.ts:172