address comments:

- `structuredOutput` typed as object rather than string
- tighten CallToolResult to codify at-least-one constraint and explicitly allow structured results to contain `content` (but not the reverse)
- update docs

Author: bhosmer-ant

docs/specification/draft/server/tools.mdx

@@ -189,7 +189,11 @@ tool annotations to be untrusted unless they come from trusted servers.</Warning
 
 ### Tool Result
 
-Tool results can contain multiple content items of different types:
+Tool results may be **structured** or **unstructured**, depending on whether the tool definition specifies an [output schema](#output-schema).
+
+**Structured** tool results are JSON objects that are valid with respect to the tool's output schema.
+
+**Unstructured** tool results can contain multiple content items of different types:
 
 #### Text Content
 
@@ -238,41 +242,93 @@ or data, behind a URI that can be subscribed to or fetched again by the client l
 
 ### Output Schema
 
-The optional `outputSchema` property provides a JSON Schema that describes the expected structure of the `structuredContent` property of a CallToolResult.
+Tools that produce structured results can use the `outputSchema` property to provide a JSON Schema describing the expected structure of their output.
 
 When a tool specifies an `outputSchema`:
 
-1. Clients **MUST** validate that the tool result contains a `structuredContent` field whose contents validate against the declared `outputSchema`.
+1. Clients **MUST** validate that results from that tool contain a `structuredContent` field whose contents validate against the declared `outputSchema`.
+
+2. Servers **MUST** provide structured results in `structuredContent` that conform to the declared `outputSchema` of the tool.
 
-2. Servers **MUST** provide tool results that conform to their declared `outputSchema`s.
+<Info>
+For backwards compatibility, a tool that declares an `outputSchema` may also return unstructured results in the `content` field.
+* If present, the unstructured result should be functionally equivalent to the structured result.
+* Clients that support `structuredContent` should ignore the `content` field if present.
+</Info>
 
 Example tool with output schema:
 
 ```json
 {
-  "name": "search_database",
-  "description": "Search a database for records",
+  "name": "get_weather_data",
+  "description": "Get current weather conditions and forecast data for a location",
   "inputSchema": {
     "type": "object",
     "properties": {
-      "query": {
+      "location": {
+        "type": "string",
+        "description": "City name or zip code"
+      },
+      "units": {
         "type": "string",
-        "description": "Search query"
+        "enum": ["celsius", "fahrenheit"],
+        "default": "celsius",
+        "description": "Temperature unit"
       }
     },
-    "required": ["query"]
+    "required": ["location"]
   },
   "outputSchema": {
-    "type": "array",
-    "items": {
-      "type": "object",
-      "properties": {
-        "id": { "type": "string" },
-        "title": { "type": "string" },
-        "url": { "type": "string" }
+    "type": "object",
+    "properties": {
+      "current": {
+        "type": "object",
+        "properties": {
+          "temperature": { "type": "number" },
+          "humidity": { "type": "number" },
+          "conditions": { "type": "string" },
+          "wind": {
+            "type": "object",
+            "properties": {
+              "speed": { "type": "number" },
+              "direction": { "type": "string" }
+            },
+            "required": ["speed", "direction"]
+          }
+        },
+        "required": ["temperature", "humidity", "conditions", "wind"]
       },
-      "required": ["id", "title"]
-    }
+      "forecast": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "date": { "type": "string", "format": "date" },
+            "high": { "type": "number" },
+            "low": { "type": "number" },
+            "conditions": { "type": "string" }
+          },
+          "required": ["date", "high", "low", "conditions"]
+        }
+      },
+      "location": {
+        "type": "object",
+        "properties": {
+          "city": { "type": "string" },
+          "country": { "type": "string" },
+          "coordinates": {
+            "type": "object",
+            "properties": {
+              "latitude": { "type": "number" },
+              "longitude": { "type": "number" }
+            },
+            "required": ["latitude", "longitude"]
+          }
+        },
+        "required": ["city", "country", "coordinates"]
+      }
+    },
+    "required": ["current", "forecast", "location"]
   }
 }
 ```
@@ -285,8 +341,37 @@ Example valid response for this tool:
   "id": 5,
   "result": {
     "structuredContent": {
-      "type": "text",
-      "text": "[{\"id\":\"doc-1\",\"title\":\"Introduction to MCP\",\"url\":\"https://example.com/docs/1\"},{\"id\":\"doc-2\",\"title\":\"Tool Usage Guide\",\"url\":\"https://example.com/docs/2\"}]"
+      "current": {
+        "temperature": 22.5,
+        "humidity": 65,
+        "conditions": "Partly cloudy",
+        "wind": {
+          "speed": 12,
+          "direction": "NW"
+        }
+      },
+      "forecast": [
+        {
+          "date": "2024-03-28",
+          "high": 25,
+          "low": 18,
+          "conditions": "Sunny"
+        },
+        {
+          "date": "2024-03-29",
+          "high": 23,
+          "low": 17,
+          "conditions": "Cloudy"
+        }
+      ],
+      "location": {
+        "city": "San Francisco",
+        "country": "US",
+        "coordinates": {
+          "latitude": 37.7749,
+          "longitude": -122.4194
+        }
+      }
     }
   }
 }

schema/draft/schema.json

@@ -101,15 +101,26 @@
             "type": "object"
         },
         "CallToolResult": {
-            "description": "The server's response to a tool call.\n\nAny errors that originate from the tool SHOULD be reported inside the result\nobject, with `isError` set to true, _not_ as an MCP protocol-level 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.",
+            "anyOf": [
+                {
+                    "$ref": "#/definitions/CallToolUnstructuredResult"
+                },
+                {
+                    "$ref": "#/definitions/CallToolStructuredResult"
+                }
+            ],
+            "description": "The server's response to a tool call.\n\nAny errors that originate from the tool SHOULD be reported inside the result\nobject, with `isError` set to true, _not_ as an MCP protocol-level 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."
+        },
+        "CallToolStructuredResult": {
+            "description": "Tool result for tools that do declare an outputSchema.",
             "properties": {
                 "_meta": {
                     "additionalProperties": {},
                     "description": "This result property is reserved by the protocol to allow clients and servers to attach additional metadata to their responses.",
                     "type": "object"
                 },
                 "content": {
-                    "description": "A list of content objects that represent the result of the tool call.",
+                    "description": "If the Tool defines an outputSchema, this field MAY be present in the result.\nTools should use this field to provide compatibility with older clients that do not support structured content.\nClients that support structured content should ignore this field.",
                     "items": {
                         "anyOf": [
                             {
@@ -133,10 +144,52 @@
                     "type": "boolean"
                 },
                 "structuredContent": {
-                    "description": "If the Tool defines an outputSchema, this field MUST contain a serialized JSON object that matches the schema.",
-                    "type": "string"
+                    "additionalProperties": {},
+                    "description": "An object containing structured tool output.\n\nIf the Tool defines an outputSchema, this field MUST be present in the result, and contain a JSON object that matches the schema.",
+                    "type": "object"
+                }
+            },
+            "required": [
+                "structuredContent"
+            ],
+            "type": "object"
+        },
+        "CallToolUnstructuredResult": {
+            "description": "Tool result for tools that do not declare an outputSchema.",
+            "properties": {
+                "_meta": {
+                    "additionalProperties": {},
+                    "description": "This result property is reserved by the protocol to allow clients and servers to attach additional metadata to their responses.",
+                    "type": "object"
+                },
+                "content": {
+                    "description": "A list of content objects that represent the result of the tool call.\n\nIf the Tool does not define an outputSchema, this field MUST be present in the result.",
+                    "items": {
+                        "anyOf": [
+                            {
+                                "$ref": "#/definitions/TextContent"
+                            },
+                            {
+                                "$ref": "#/definitions/ImageContent"
+                            },
+                            {
+                                "$ref": "#/definitions/AudioContent"
+                            },
+                            {
+                                "$ref": "#/definitions/EmbeddedResource"
+                            }
+                        ]
+                    },
+                    "type": "array"
+                },
+                "isError": {
+                    "description": "Whether the tool call ended in an error.\n\nIf not set, this is assumed to be false (the call was successful).",
+                    "type": "boolean"
                 }
             },
+            "required": [
+                "content"
+            ],
             "type": "object"
         },
         "CancelledNotification": {
@@ -360,6 +413,25 @@
             ],
             "type": "object"
         },
+        "ContentList": {
+            "items": {
+                "anyOf": [
+                    {
+                        "$ref": "#/definitions/TextContent"
+                    },
+                    {
+                        "$ref": "#/definitions/ImageContent"
+                    },
+                    {
+                        "$ref": "#/definitions/AudioContent"
+                    },
+                    {
+                        "$ref": "#/definitions/EmbeddedResource"
+                    }
+                ]
+            },
+            "type": "array"
+        },
         "CreateMessageRequest": {
             "description": "A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.",
             "properties": {
@@ -1906,7 +1978,10 @@
                     "$ref": "#/definitions/ListToolsResult"
                 },
                 {
-                    "$ref": "#/definitions/CallToolResult"
+                    "$ref": "#/definitions/CallToolUnstructuredResult"
+                },
+                {
+                    "$ref": "#/definitions/CallToolStructuredResult"
                 },
                 {
                     "$ref": "#/definitions/CompleteResult"
@@ -2054,7 +2129,7 @@
                 },
                 "outputSchema": {
                     "additionalProperties": true,
-                    "description": "A JSON Schema object defining the structure of the tool's output.\n\nIf set, a CallToolResult for this Tool MUST contain a structuredContent field whose contents validate against this schema.",
+                    "description": "An optional JSON Schema object defining the structure of the tool's output.\n\nIf set, a CallToolResult for this Tool MUST contain a structuredContent field whose contents validate against this schema.\nIf not set, a CallToolResult for this Tool MUST contain a content field.",
                     "properties": {},
                     "type": "object"
                 }

schema/draft/schema.ts

@@ -695,20 +695,51 @@ export interface ListToolsResult extends PaginatedResult {
  * server does not support tool calls, or any other exceptional conditions,
  * should be reported as an MCP error response.
  */
-export interface CallToolResult extends Result {
+export type CallToolResult = CallToolUnstructuredResult | CallToolStructuredResult;
+
+export type ContentList = (TextContent | ImageContent | AudioContent | EmbeddedResource)[];
+
+/**
+ * Tool result for tools that do not declare an outputSchema.
+ */
+export interface CallToolUnstructuredResult extends Result {
   /**
    * A list of content objects that represent the result of the tool call.
    *
    * If the Tool does not define an outputSchema, this field MUST be present in the result.
    */
-  content?: (TextContent | ImageContent | AudioContent | EmbeddedResource)[];
+  content: ContentList;
 
   /**
-   * A string containing structured tool output.
+   * Structured output must not be provided in an unstructured tool result.
+   */
+  structuredContent: never;
+
+  /**
+   * Whether the tool call ended in an error.
    *
-   * If the Tool defines an outputSchema, this field MUST be present in the result, and contain a serialized JSON object that matches the schema.
+   * If not set, this is assumed to be false (the call was successful).
    */
-  structuredContent?: string;
+  isError?: boolean;
+}
+
+/**
+ * Tool result for tools that do declare an outputSchema.
+ */
+export interface CallToolStructuredResult extends Result {
+  /**
+   * An object containing structured tool output.
+   *
+   * If the Tool defines an outputSchema, this field MUST be present in the result, and contain a JSON object that matches the schema.
+   */
+  structuredContent: { [key: string]: unknown };
+
+  /**
+   * If the Tool defines an outputSchema, this field MAY be present in the result.
+   * Tools should use this field to provide compatibility with older clients that do not support structured content.
+   * Clients that support structured content should ignore this field.
+   */
+  content?: ContentList;
 
   /**
    * Whether the tool call ended in an error.
@@ -718,6 +749,7 @@ export interface CallToolResult extends Result {
   isError?: boolean;
 }
 
+
 /**
  * Used by the client to invoke a tool provided by the server.
  */