Merge pull request modelcontextprotocol#2425 from jonathanhefner/reorganize-tool-error-handling-section

Reorganize tool error handling section for clarity

Author: localden

docs/specification/draft/server/tools.mdx

@@ -454,51 +454,49 @@ Providing an output schema helps clients and LLMs understand and properly handle
 
 Tools use two error reporting mechanisms:
 
-1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
-   - Unknown tools
+1. **Protocol Errors** indicate issues with the request structure itself that models are less likely to be able to fix:
+   - Unknown tool
    - Malformed requests (requests that fail to satisfy [CallToolRequest schema](/specification/draft/schema#calltoolrequest))
    - Server errors
 
-2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
+   They are returned as standard JSON-RPC errors:
+
+   ```json
+   {
+     "jsonrpc": "2.0",
+     "id": 3,
+     "error": {
+       "code": -32602,
+       "message": "Unknown tool: invalid_tool_name"
+     }
+   }
+   ```
+
+2. **Tool Execution Errors** contain actionable feedback that language models can use to self-correct and retry with adjusted parameters:
    - API failures
    - Input validation errors (e.g., date in wrong format, value out of range)
    - Business logic errors
 
-**Tool Execution Errors** contain actionable feedback that language models can use to self-correct and retry with adjusted parameters.
-**Protocol Errors** indicate issues with the request structure itself that models are less likely to be able to fix.
-Clients **SHOULD** provide tool execution errors to language models to enable self-correction.
-Clients **MAY** provide protocol errors to language models, though these are less likely to result in successful recovery.
-
-Example protocol error:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "error": {
-    "code": -32602,
-    "message": "Unknown tool: invalid_tool_name"
-  }
-}
-```
-
-Example tool execution error (input validation):
+   They are reported in tool results with `isError: true`:
+
+   ```json
+   {
+     "jsonrpc": "2.0",
+     "id": 4,
+     "result": {
+       "content": [
+         {
+           "type": "text",
+           "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
+         }
+       ],
+       "isError": true
+     }
+   }
+   ```
 
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 4,
-  "result": {
-    "content": [
-      {
-        "type": "text",
-        "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
-      }
-    ],
-    "isError": true
-  }
-}
-```
+Clients **MAY** provide protocol errors to language models, though these are less likely to result in successful recovery.
+Clients **SHOULD** provide tool execution errors to language models to enable self-correction.
 
 ## Security Considerations