add CallToolResult.structuredContent

Author: bhosmer-ant

docs/specification/draft/server/tools.mdx

@@ -181,7 +181,7 @@ A tool definition includes:
 - `name`: Unique identifier for the tool
 - `description`: Human-readable description of functionality
 - `inputSchema`: JSON Schema defining expected parameters
-- `outputSchema`: Optional JSON Schema defining the expected output structure
+- `outputSchema`: Optional JSON Schema defining expected output structure
 - `annotations`: optional properties describing tool behavior
 
 <Warning>For trust & safety and security, clients **MUST** consider
@@ -238,18 +238,13 @@ 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 tool's output. This schema applies to the `text` property of the TextContent object returned by the tool.
+The optional `outputSchema` property provides a JSON Schema that describes the expected structure of the `structuredContent` property of a CallToolResult.
 
 When a tool specifies an `outputSchema`:
 
-1. Clients **SHOULD** validate that the tool's result:
-   - Contains exactly one content item
-   - This item is a `TextContent` object
-   - The `text` property of this object validates against the schema
+1. Clients **MUST** validate that the tool result contains a `structuredContent` field whose contents validate against the declared `outputSchema`.
 
-2. Servers **SHOULD**:
-   - Provide responses that conform to their declared schema
-   - Use proper JSON or structured formats in their responses when the schema specifies structured data
+2. Servers **MUST** provide tool results that conform to their declared `outputSchema`s.
 
 Example tool with output schema:
 
@@ -289,21 +284,19 @@ Example valid response for this tool:
   "jsonrpc": "2.0",
   "id": 5,
   "result": {
-    "content": [
-      {
-        "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\"}]"
-      }
-    ]
+    "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\"}]"
+    }
   }
 }
 ```
 
-The `outputSchema` helps clients and LLMs understand and properly handle tool outputs by:
+The `outputSchema` helps clients and LLMs understand and properly handle structured tool outputs by:
 
-- Enabling schema validation of responses
+- Enabling strict schema validation of responses
 - Providing type information for better integration with programming languages
-- Guiding LLMs to properly parse and utilize the returned data
+- Guiding clients and LLMs to properly parse and utilize the returned data
 - Supporting better documentation and developer experience
 
 ## Error Handling

schema/draft/schema.json

@@ -109,6 +109,7 @@
                     "type": "object"
                 },
                 "content": {
+                    "description": "A list of content objects that represent the result of the tool call.",
                     "items": {
                         "anyOf": [
                             {
@@ -130,11 +131,12 @@
                 "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"
+                },
+                "structuredContent": {
+                    "description": "If the Tool defines an outputSchema, this field MUST contain a serialized JSON object that matches the schema.",
+                    "type": "string"
                 }
             },
-            "required": [
-                "content"
-            ],
             "type": "object"
         },
         "CancelledNotification": {
@@ -2052,7 +2054,7 @@
                 },
                 "outputSchema": {
                     "additionalProperties": true,
-                    "description": "A JSON Schema object defining the structure of the tool's output.\n\nIf set, a client SHOULD validate a CallToolResult for this Tool as follows:\n1. check that the length of the result's `content` property == 1\n2. check that this single item is a `TextContent` object\n3. validate this object's `text` property against this schema.\n\nIn other words, for a CallToolResult to be valid with respect to this schema,\nit must first satisfy the precondition that its payload be a single TextContent \nobject.",
+                    "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.",
                     "properties": {},
                     "type": "object"
                 }

schema/draft/schema.ts

@@ -696,7 +696,19 @@ export interface ListToolsResult extends PaginatedResult {
  * should be reported as an MCP error response.
  */
 export interface CallToolResult extends Result {
-  content: (TextContent | ImageContent | AudioContent | EmbeddedResource)[];
+  /**
+   * 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)[];
+
+  /**
+   * A string containing structured tool output.
+   *
+   * If the Tool defines an outputSchema, this field MUST be present in the result, and contain a serialized JSON object that matches the schema.
+   */
+  structuredContent?: string;
 
   /**
    * Whether the tool call ended in an error.
@@ -804,16 +816,10 @@ export interface Tool {
   };
 
   /**
-   * A JSON Schema object defining the structure of the tool's output.
-   *
-   * If set, a client SHOULD validate a CallToolResult for this Tool as follows:
-   * 1. check that the length of the result's `content` property == 1
-   * 2. check that this single item is a `TextContent` object
-   * 3. validate this object's `text` property against this schema.
+   * An optional JSON Schema object defining the structure of the tool's output.
    *
-   * In other words, for a CallToolResult to be valid with respect to this schema,
-   * it must first satisfy the precondition that its payload be a single TextContent
-   * object.
+   * If set, a CallToolResult for this Tool MUST contain a structuredContent field whose contents validate against this schema.
+   * If not set, a CallToolResult for this Tool MUST contain a content field.
    */
   outputSchema?: object;