Recommend errors in tool calls be reported inline

Author: jspahrsummers

docs/spec/tools.md

@@ -274,14 +274,17 @@ Upon receiving this notification, clients SHOULD request an updated tool list us
 
 ## Error Handling
 
-Clients MUST be prepared to handle cases where listed tools become unavailable between listing and invocation attempts. Servers SHOULD provide appropriate error responses in such scenarios.
+Error handling for tools follows two distinct paths depending on the type of error:
 
-Servers MUST return error responses when:
+1. Protocol-level errors (like unknown tools or invalid parameters) MUST be reported as JSON-RPC error responses
+2. Tool execution errors SHOULD be reported inside successful CallToolResult responses
+
+For protocol-level errors, servers MUST return error responses when:
 - An unknown tool is requested
 - Invalid arguments are provided
-- The tool execution fails
+- The server does not support tool calls
 
-Example error response:
+Example protocol error response for invalid parameters:
 ```json
 {
   "jsonrpc": "2.0",
@@ -296,6 +299,36 @@ Example error response:
 }
 ```
 
+Example protocol error response for an unknown tool:
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "error": {
+    "code": -32601,
+    "message": "Method not found",
+    "data": {
+      "reason": "Unknown tool: invalid_tool_name"
+    }
+  }
+}
+```
+
+For errors that occur during tool execution (like API failures or invalid data), servers SHOULD return these as part of a successful `CallToolResult`. This allows the LLM to see and potentially handle the error condition:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "result": {
+    "toolResult": {
+      "error": "No search results found for query: 'widgets manufactured in 1972'",
+      "status": "empty_results"
+    }
+  }
+}
+```
+
 ## Security Considerations
 
 Implementations MUST carefully consider the security implications of exposing tools, especially when dealing with sensitive data or external services. Proper authentication and authorization mechanisms SHOULD be in place to prevent unauthorized access to tools.

schema/schema.json

@@ -54,7 +54,7 @@
             "type": "object"
         },
         "CallToolResult": {
-            "description": "The server's response to a tool call.",
+            "description": "The server's response to a tool call.\n\nAny errors that originate from the tool SHOULD be reported inside the result\nobject—i.e., as part of an MCP successful result, not as an MCP error\nresponse. Otherwise, the LLM would not be able to see that an error occurred\nand self-correct.\n\nHowever, any errors in _finding_ the tool, an error indicating that the\nserver does not support tool calls, or any other exceptional conditions,\nshould be reported as an MCP error response.",
             "properties": {
                 "_meta": {
                     "additionalProperties": {},

schema/schema.ts

@@ -569,6 +569,15 @@ export interface ListToolsResult extends PaginatedResult {
 
 /**
  * The server's response to a tool call.
+ *
+ * Any errors that originate from the tool SHOULD be reported inside the result
+ * object—i.e., as part of an MCP successful result, not as an MCP error
+ * response. Otherwise, the LLM would not be able to see that an error occurred
+ * and self-correct.
+ *
+ * However, any errors in _finding_ the tool, an error indicating that the
+ * server does not support tool calls, or any other exceptional conditions,
+ * should be reported as an MCP error response.
  */
 export interface CallToolResult extends Result {
   toolResult: unknown;