RFC: add Tool.outputSchema and CallToolResult.structuredContent
#371
+289
−5
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -181,14 +181,19 @@ 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 expected output structure | ||
| - `annotations`: optional properties describing tool behavior | ||
|
|
||
| <Warning>For trust & safety and security, clients **MUST** consider | ||
| tool annotations to be untrusted unless they come from trusted servers.</Warning> | ||
|
|
||
| ### Tool Result | ||
|
|
||
| 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 | ||
|
|
||
|
|
@@ -235,6 +240,150 @@ or data, behind a URI that can be subscribed to or fetched again by the client l | |
| } | ||
| ``` | ||
|
|
||
| ### Output Schema | ||
|
|
||
| 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 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. | ||
|
|
||
| <Info> | ||
| For backwards compatibility, a tool that declares an `outputSchema` may also return unstructured results in the `content` field. | ||
|
Member
There was a problem hiding this comment. Should this be based on the MCP client version string during version negotiation rather than doing this unconditionally?
Contributor
Author
There was a problem hiding this comment. Seems useful to avoid mandating complex version-dependent logic here. (Paraphrasing offline discussion with @ihrpr:) In practice the SDKs will be handling construction of actual results, so it's useful to leave some freedom, and client/server devs will be spared the implementation details in any case. But even if both formats are sent unconditionally, the perf impact isn't huge, definitely not worth baking complexity into the spec to avoid. There was a problem hiding this comment. Why does it say "for backwards compatibility"? Does that mean structured output is always preferable over unstructured output? Why not specifically encourage tools to return both an unstructured and a structured response, so that the MCP client can pick the desired one based on the use case? For example, an unstructured response can be optimized for an LLM to read (e.g. when chatting with Claude), and a structured result can be used when further transformations are required. Furthermore, you might also want to allow structured results contain extra data like IDs or timestamps that are not very meaningful for an LLM, but can be useful when doing data transformations (This also contradicts the bullet points below). |
||
| * If present, the unstructured result should be functionally equivalent to the structured result. (For example, serialized JSON can be returned in a `TextContent` block.) | ||
| * Clients that support `structuredContent` should ignore the `content` field if present. | ||
| </Info> | ||
|
|
||
| Example tool with output schema: | ||
|
|
||
| ```json | ||
| { | ||
| "name": "get_weather_data", | ||
| "description": "Get current weather conditions and forecast data for a location", | ||
| "inputSchema": { | ||
| "type": "object", | ||
| "properties": { | ||
| "location": { | ||
| "type": "string", | ||
| "description": "City name or zip code" | ||
| }, | ||
| "units": { | ||
| "type": "string", | ||
| "enum": ["celsius", "fahrenheit"], | ||
| "default": "celsius", | ||
| "description": "Temperature unit" | ||
| } | ||
| }, | ||
| "required": ["location"] | ||
| }, | ||
| "outputSchema": { | ||
| "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"] | ||
| }, | ||
| "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"] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Example valid response for this tool: | ||
|
Member
There was a problem hiding this comment. Can we also add an example for a valid response that is b/w comaptible? |
||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 5, | ||
| "result": { | ||
| "structuredContent": { | ||
| "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 | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The `outputSchema` helps clients and LLMs understand and properly handle structured tool outputs by: | ||
|
|
||
| - Enabling strict schema validation of responses | ||
| - Providing type information for better integration with programming languages | ||
| - Guiding clients and LLMs to properly parse and utilize the returned data | ||
| - Supporting better documentation and developer experience | ||
|
|
||
| ## Error Handling | ||
|
|
||
| Tools use two error reporting mechanisms: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we explicitly have some b/w compat recommendations based on the MCP version string header i.e. if the client is on an older version, we return the json serialized text in a content text block?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My feeling was that we should avoid being overly proscriptive/fine-grained about logic based on client versioning, but adding a suggestion about serialized JSON in a text block is a great idea. Thanks!