Merge pull request modelcontextprotocol#603 from modelcontextprotocol/basil/resource_reference_tool_result

add ResourceLink to CallToolResult

Author: bhosmer-ant

docs/specification/draft/changelog.mdx

@@ -21,6 +21,8 @@ the previous revision, [2025-03-26](/specification/2025-03-26).
 5. Added support for **[elicitation](client/elicitation)**, enabling servers to request additional
    information from users during interactions.
    (PR [#382](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/382))
+6. Added support for **[resource links](/specification/draft/server/tools#resource-links)** in
+   tool call results. (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603))
 
 ## Other schema changes
 

docs/specification/draft/server/tools.mdx

@@ -230,18 +230,38 @@ Tool results may contain [**structured**](#structured-content) or **unstructured
 }
 ```
 
+#### Resource Links
+
+A tool **MAY** return links to [Resources](/specification/draft/server/resources), to provide additional context
+or data. In this case, the tool will return a URI that can be subscribed to or fetched by the client:
+
+```json
+{
+  "type": "resource_link",
+  "uri": "file:///project/src/main.rs",
+  "name": "main.rs",
+  "description": "Primary application entry point",
+  "mimeType": "text/x-rust"
+}
+```
+
+<Info>
+  Resource links returned by tools are not guaranteed to appear in the results
+  of a `resources/list` request.
+</Info>
+
 #### Embedded Resources
 
-[Resources](/specification/draft/server/resources) **MAY** be embedded, to provide additional context
-or data, behind a URI that can be subscribed to or fetched again by the client later:
+A tool **MAY** return embedded [Resource contents](/specification/draft/server/resources), to provide additional context
+or data, along with a URI that can be subscribed to or fetched again by the client later:
 
 ```json
 {
   "type": "resource",
   "resource": {
-    "uri": "resource://example",
-    "mimeType": "text/plain",
-    "text": "Resource content"
+    "uri": "file:///project/src/main.rs",
+    "mimeType": "text/x-rust",
+    "text": "fn main() {\n    println!(\"Hello world!\");\n}"
   }
 }
 ```

schema/draft/schema.json

@@ -634,7 +634,16 @@ export type Role = "user" | "assistant";
  */
 export interface PromptMessage {
   role: Role;
-  content: TextContent | ImageContent | AudioContent | EmbeddedResource;
+  content: ContentBlock;
+}
+
+/**
+ * A resource that the server is capable of reading, included in a prompt or tool call result.
+ *
+ * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.
+ */
+export interface ResourceLink extends Resource {
+  type: "resource_link";
 }
 
 /**
@@ -652,7 +661,6 @@ export interface EmbeddedResource {
    */
   annotations?: Annotations;
 }
-
 /**
  * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.
  */
@@ -682,7 +690,7 @@ export interface CallToolResult extends Result {
   /**
    * A list of content objects that represent the unstructured result of the tool call.
    */
-  content: (TextContent | ImageContent | AudioContent | EmbeddedResource)[];
+  content: ContentBlock[];
 
   /**
    * An optional JSON object that represents the structured result of the tool call.
@@ -953,6 +961,14 @@ export interface Annotations {
   priority?: number;
 }
 
+/**  */
+export type ContentBlock =
+  | TextContent
+  | ImageContent
+  | AudioContent
+  | ResourceLink
+  | EmbeddedResource;
+
 /**
  * Text provided to or from an LLM.
  */
@@ -1291,7 +1307,7 @@ export interface EnumSchema {
   title?: string;
   description?: string;
   enum: string[];
-  enumNames?: string[];  // Display names for enum values
+  enumNames?: string[]; // Display names for enum values
 }
 
 /**
@@ -1335,7 +1351,11 @@ export type ClientNotification =
   | InitializedNotification
   | RootsListChangedNotification;
 
-export type ClientResult = EmptyResult | CreateMessageResult | ListRootsResult | ElicitResult;
+export type ClientResult =
+  | EmptyResult
+  | CreateMessageResult
+  | ListRootsResult
+  | ElicitResult;
 
 /* Server messages */
 export type ServerRequest =