add Tool.outputSchema

Author: bhosmer-ant

docs/specification/draft/server/tools.mdx

@@ -181,6 +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
 - `annotations`: optional properties describing tool behavior
 
 <Warning>For trust & safety and security, clients **MUST** consider
@@ -235,6 +236,76 @@ 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.
+
+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
+
+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
+
+Example tool with output schema:
+
+```json
+{
+  "name": "search_database",
+  "description": "Search a database for records",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": {
+        "type": "string",
+        "description": "Search query"
+      }
+    },
+    "required": ["query"]
+  },
+  "outputSchema": {
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "url": { "type": "string" }
+      },
+      "required": ["id", "title"]
+    }
+  }
+}
+```
+
+Example valid response for this tool:
+
+```json
+{
+  "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\"}]"
+      }
+    ]
+  }
+}
+```
+
+The `outputSchema` helps clients and LLMs understand and properly handle tool outputs by:
+
+- Enabling schema validation of responses
+- Providing type information for better integration with programming languages
+- Guiding LLMs to properly parse and utilize the returned data
+- Supporting better documentation and developer experience
+
 ## Error Handling
 
 Tools use two error reporting mechanisms:

schema/draft/schema.json

@@ -2049,6 +2049,12 @@
                 "name": {
                     "description": "The name of the tool.",
                     "type": "string"
+                },
+                "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.",
+                    "properties": {},
+                    "type": "object"
                 }
             },
             "required": [

schema/draft/schema.ts

@@ -803,6 +803,20 @@ export interface Tool {
     required?: string[];
   };
 
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  outputSchema?: object;
+
   /**
    * Optional additional tool information.
    */