fix(langchain): add missing section on handling tool errors (#1622)

The section was missing examples.

Author: christian-bromann

src/oss/javascript/migrate/langchain-v1.mdx

@@ -396,36 +396,51 @@ The `tools` argument to `createAgent` accepts:
 - LangChain tool instances
 - Objects that represent built-in provider tools
 
-Use middleware `wrapToolCall` to centralize error handling and logging for tools.
+#### Handling tool errors
+
+You can now configure the handling of tool errors with middleware implementing the `wrapToolCall` method.
 
 <CodeGroup>
 ```typescript v1 (new)
-import { createAgent, createMiddleware } from "langchain";
+import { createAgent, createMiddleware, ToolMessage } from "langchain";
 
-const errorHandling = createMiddleware({
-  name: "ToolErrors",
+const handleToolErrors = createMiddleware({
+  name: "HandleToolErrors",
   wrapToolCall: async (request, handler) => {
     try {
       return await handler(request);
-    } catch (err) {
-      return `Error executing ${request.toolName}: ${String(err)}`;
+    } catch (error) {
+      // Only handle errors that occur during tool execution due to invalid inputs
+      // that pass schema validation but fail at runtime (e.g., invalid SQL syntax).
+      // Do NOT handle:
+      // - Network failures (use tool retry middleware instead)
+      // - Incorrect tool implementation errors (should bubble up)
+      // - Schema mismatch errors (already auto-handled by the framework)
+      //
+      // Return a custom error message to the model
+      return new ToolMessage({
+        content: `Tool error: Please check your input and try again. (${error})`,
+        tool_call_id: request.toolCall.id!,
+      });
     }
   },
 });
 
 const agent = createAgent({
   model: "claude-sonnet-4-5-20250929",
   tools: [checkWeather, searchWeb],
-  middleware: [errorHandling],
+  middleware: [handleToolErrors],
 });
 ```
 ```typescript v0 (old)
-import { createReactAgent } from "@langchain/langgraph/prebuilts";
+import { createReactAgent, ToolNode } from "@langchain/langgraph/prebuilts";
 
 const agent = createReactAgent({
   model: "claude-sonnet-4-5-20250929",
-  tools: [checkWeather, searchWeb],
-  // Error handling commonly implemented inside tool code or post hooks
+  tools: new ToolNode(
+    [checkWeather, searchWeb],
+    { handleToolErrors: true } // [!code highlight]
+  ),
 });
 ```
 </CodeGroup>

src/oss/python/migrate/langchain-v1.mdx

@@ -592,19 +592,52 @@ You can now configure the handling of tool errors with middleware implementing t
 
 <CodeGroup>
 ```python v1 (new)
+from langchain.agents import create_agent
+from langchain.agents.middleware import wrap_tool_call
+from langchain.messages import ToolMessage
+
 
 @wrap_tool_call
-def retry_on_error(request, handler):
-    max_retries = 3
-    for attempt in range(max_retries):
-        try:
-            return handler(request)
-        except Exception:
-            if attempt == max_retries - 1:
-                raise
+def handle_tool_errors(request, handler):
+    """Handle tool execution errors with custom messages."""
+    try:
+        return handler(request)
+    except Exception as e:
+        # Only handle errors that occur during tool execution due to invalid inputs
+        # that pass schema validation but fail at runtime (e.g., invalid SQL syntax).
+        # Do NOT handle:
+        # - Network failures (use tool retry middleware instead)
+        # - Incorrect tool implementation errors (should bubble up)
+        # - Schema mismatch errors (already auto-handled by the framework)
+        #
+        # Return a custom error message to the model
+        return ToolMessage(
+            content=f"Tool error: Please check your input and try again. ({str(e)})",
+            tool_call_id=request.tool_call["id"]
+        )
+
+agent = create_agent(
+    model="claude-sonnet-4-5-20250929",
+    tools=[check_weather, search_web],
+    middleware=[handle_tool_errors]
+)
 ```
 ```python v0 (old)
-# Example coming soon
+from langgraph.prebuilt import create_react_agent, ToolNode
+from langchain.messages import ToolMessage
+
+
+def handle_tool_error(error: Exception) -> str:
+    """Custom error handler function."""
+    return f"Tool error: Please check your input and try again. ({str(error)})"
+
+agent = create_react_agent(
+    model="claude-sonnet-4-5-20250929",
+    tools=ToolNode(
+        [check_weather, search_web],
+        handle_tool_errors=handle_tool_error  # [!code highlight]
+    )
+)
 ```
 </CodeGroup>