From ace8816516299674ef35ee59dcbdcc6257697e3b Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Fri, 30 May 2025 12:47:11 -0400 Subject: [PATCH 01/13] add ResourceReference to CallToolResult --- schema/draft/schema.json | 3 +++ schema/draft/schema.ts | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 5c860cf18..c47b7ce7d 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -144,6 +144,9 @@ }, { "$ref": "#/definitions/EmbeddedResource" + }, + { + "$ref": "#/definitions/ResourceReference" } ] }, diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index cb53ec029..f25f0ee9c 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -682,7 +682,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: (TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceReference)[]; /** * An optional JSON object that represents the structured result of the tool call. From 307ab83e7949ed313a3262137b176386d7a44d99 Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Wed, 4 Jun 2025 08:25:49 +0100 Subject: [PATCH 02/13] Include a discriminated LinkedResource for embedding Resources in Tool Results and Prompts --- schema/draft/schema.json | 69 ++++++++++++++++++++++------------------ schema/draft/schema.ts | 33 ++++++++++++++++--- 2 files changed, 67 insertions(+), 35 deletions(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index c47b7ce7d..8197534d2 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -132,23 +132,7 @@ "content": { "description": "A list of content objects that represent the unstructured result of the tool call.", "items": { - "anyOf": [ - { - "$ref": "#/definitions/TextContent" - }, - { - "$ref": "#/definitions/ImageContent" - }, - { - "$ref": "#/definitions/AudioContent" - }, - { - "$ref": "#/definitions/EmbeddedResource" - }, - { - "$ref": "#/definitions/ResourceReference" - } - ] + "$ref": "#/definitions/ContentBlock" }, "type": "array" }, @@ -410,6 +394,25 @@ ], "type": "object" }, + "ContentBlock": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + }, + { + "$ref": "#/definitions/EmbeddedResource" + }, + { + "$ref": "#/definitions/LinkedResource" + } + ] + }, "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": { @@ -991,6 +994,23 @@ ], "type": "object" }, + "LinkedResource": { + "description": "A resource descriptor, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render linked resources for the benefit\nof the LLM and/or the user.", + "properties": { + "resource": { + "$ref": "#/definitions/Resource" + }, + "type": { + "const": "linkedresource", + "type": "string" + } + }, + "required": [ + "resource", + "type" + ], + "type": "object" + }, "ListPromptsRequest": { "description": "Sent from the client to request a list of prompts and prompt templates the server has.", "properties": { @@ -1559,20 +1579,7 @@ "description": "Describes a message returned as part of a prompt.\n\nThis is similar to `SamplingMessage`, but also supports the embedding of\nresources from the MCP server.", "properties": { "content": { - "anyOf": [ - { - "$ref": "#/definitions/TextContent" - }, - { - "$ref": "#/definitions/ImageContent" - }, - { - "$ref": "#/definitions/AudioContent" - }, - { - "$ref": "#/definitions/EmbeddedResource" - } - ] + "$ref": "#/definitions/ContentBlock" }, "role": { "$ref": "#/definitions/Role" diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index f25f0ee9c..1999e014a 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -634,7 +634,7 @@ export type Role = "user" | "assistant"; */ export interface PromptMessage { role: Role; - content: TextContent | ImageContent | AudioContent | EmbeddedResource; + content: ContentBlock; } /** @@ -653,6 +653,19 @@ export interface EmbeddedResource { annotations?: Annotations; } +/** + * + * A resource descriptor, embedded into a prompt or tool call result. + * + * It is up to the client how best to render linked resources for the benefit + * of the LLM and/or the user. + * + */ +export interface LinkedResource { + type: "linkedresource"; + resource: Resource; +} + /** * 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 +695,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 | ResourceReference)[]; + content: ContentBlock[]; /** * An optional JSON object that represents the structured result of the tool call. @@ -953,6 +966,14 @@ export interface Annotations { priority?: number; } +/** */ +export type ContentBlock = + | TextContent + | ImageContent + | AudioContent + | EmbeddedResource + | LinkedResource; + /** * Text provided to or from an LLM. */ @@ -1291,7 +1312,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 +1356,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 = From 4641c3e9378781a12d9dee6e563eecdf6859a5ab Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Wed, 4 Jun 2025 09:26:50 +0100 Subject: [PATCH 03/13] preparing documentation updates --- docs/specification/draft/server/tools.mdx | 6 +++++ schema/draft/schema.ts | 32 +++++++++++------------ 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/docs/specification/draft/server/tools.mdx b/docs/specification/draft/server/tools.mdx index 32512901f..8ab4cf341 100644 --- a/docs/specification/draft/server/tools.mdx +++ b/docs/specification/draft/server/tools.mdx @@ -230,6 +230,12 @@ Tool results may contain [**structured**](#structured-content) or **unstructured } ``` +#### Linked Resources + +[Resources](/specification/draft/server/resources) **MAY** be linked, to provide additional context +or data, behind a URI that can be subscribed to or fetched again by the client later: + + #### Embedded Resources [Resources](/specification/draft/server/resources) **MAY** be embedded, to provide additional context diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index 1999e014a..d4de1fc10 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -637,6 +637,20 @@ export interface PromptMessage { content: ContentBlock; } +/** + * + * A reference to a resource descriptor, embedded into a prompt or tool call result. + * + * It is up to the client how best to render linked resources for the benefit + * of the LLM and/or the user. + * + */ +export interface LinkedResource { + type: "linkedresource"; + resource: Resource; +} + + /** * The contents of a resource, embedded into a prompt or tool call result. * @@ -652,20 +666,6 @@ export interface EmbeddedResource { */ annotations?: Annotations; } - -/** - * - * A resource descriptor, embedded into a prompt or tool call result. - * - * It is up to the client how best to render linked resources for the benefit - * of the LLM and/or the user. - * - */ -export interface LinkedResource { - type: "linkedresource"; - resource: Resource; -} - /** * 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. */ @@ -971,8 +971,8 @@ export type ContentBlock = | TextContent | ImageContent | AudioContent - | EmbeddedResource - | LinkedResource; + | LinkedResource + | EmbeddedResource; /** * Text provided to or from an LLM. From 22e8b3347a241e6e63ae820fb7de710373750937 Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Wed, 4 Jun 2025 11:55:54 +0100 Subject: [PATCH 04/13] changed ordering, rerun schema gen --- schema/draft/schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 8197534d2..59c402b97 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -406,10 +406,10 @@ "$ref": "#/definitions/AudioContent" }, { - "$ref": "#/definitions/EmbeddedResource" + "$ref": "#/definitions/LinkedResource" }, { - "$ref": "#/definitions/LinkedResource" + "$ref": "#/definitions/EmbeddedResource" } ] }, @@ -995,7 +995,7 @@ "type": "object" }, "LinkedResource": { - "description": "A resource descriptor, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render linked resources for the benefit\nof the LLM and/or the user.", + "description": "A reference to a resource descriptor, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render linked resources for the benefit\nof the LLM and/or the user.", "properties": { "resource": { "$ref": "#/definitions/Resource" From 1d3f8a4fefa5308dc16dbe5c9f97886a500d764b Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Wed, 4 Jun 2025 08:25:49 +0100 Subject: [PATCH 05/13] Include a discriminated LinkedResource for embedding Resources in Tool Results and Prompts --- schema/draft/schema.ts | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index d4de1fc10..0f4b17473 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -637,20 +637,6 @@ export interface PromptMessage { content: ContentBlock; } -/** - * - * A reference to a resource descriptor, embedded into a prompt or tool call result. - * - * It is up to the client how best to render linked resources for the benefit - * of the LLM and/or the user. - * - */ -export interface LinkedResource { - type: "linkedresource"; - resource: Resource; -} - - /** * The contents of a resource, embedded into a prompt or tool call result. * @@ -666,6 +652,20 @@ export interface EmbeddedResource { */ annotations?: Annotations; } + +/** + * + * A resource descriptor, embedded into a prompt or tool call result. + * + * It is up to the client how best to render linked resources for the benefit + * of the LLM and/or the user. + * + */ +export interface LinkedResource { + type: "linkedresource"; + resource: Resource; +} + /** * 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. */ From f156eb775f0521be6cf42b91e91e36e60b4808d5 Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Wed, 4 Jun 2025 09:26:50 +0100 Subject: [PATCH 06/13] preparing documentation updates --- schema/draft/schema.ts | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index 0f4b17473..d4de1fc10 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -637,6 +637,20 @@ export interface PromptMessage { content: ContentBlock; } +/** + * + * A reference to a resource descriptor, embedded into a prompt or tool call result. + * + * It is up to the client how best to render linked resources for the benefit + * of the LLM and/or the user. + * + */ +export interface LinkedResource { + type: "linkedresource"; + resource: Resource; +} + + /** * The contents of a resource, embedded into a prompt or tool call result. * @@ -652,20 +666,6 @@ export interface EmbeddedResource { */ annotations?: Annotations; } - -/** - * - * A resource descriptor, embedded into a prompt or tool call result. - * - * It is up to the client how best to render linked resources for the benefit - * of the LLM and/or the user. - * - */ -export interface LinkedResource { - type: "linkedresource"; - resource: Resource; -} - /** * 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. */ From e8568dd3856be7f84b8f52c784a3ebea10d6fafa Mon Sep 17 00:00:00 2001 From: evalstate <1936278+evalstate@users.noreply.github.com> Date: Thu, 5 Jun 2025 08:41:57 +0100 Subject: [PATCH 07/13] update to is-a rather than contains-a relationship for linked resource. --- schema/draft/schema.json | 31 +++++++++++++++++++++++++++---- schema/draft/schema.ts | 4 +--- 2 files changed, 28 insertions(+), 7 deletions(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 59c402b97..4f514562b 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -997,17 +997,40 @@ "LinkedResource": { "description": "A reference to a resource descriptor, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render linked resources for the benefit\nof the LLM and/or the user.", "properties": { - "resource": { - "$ref": "#/definitions/Resource" + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "A human-readable name for this resource.\n\nThis can be used by clients to populate UI elements.", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" }, "type": { "const": "linkedresource", "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" } }, "required": [ - "resource", - "type" + "name", + "type", + "uri" ], "type": "object" }, diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index d4de1fc10..66b001637 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -645,12 +645,10 @@ export interface PromptMessage { * of the LLM and/or the user. * */ -export interface LinkedResource { +export interface LinkedResource extends Resource { type: "linkedresource"; - resource: Resource; } - /** * The contents of a resource, embedded into a prompt or tool call result. * From 5867635ebf59678d680e084a42034d2cdf8edf71 Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Thu, 5 Jun 2025 11:21:58 -0400 Subject: [PATCH 08/13] add docs --- docs/specification/draft/changelog.mdx | 1 + docs/specification/draft/server/tools.mdx | 21 ++++++++++++++++----- schema/draft/schema.ts | 2 +- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 6c87cebec..000af4342 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -21,6 +21,7 @@ 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 **[linked resources](http://localhost:3001/specification/draft/server/tools#linked-resources)** in tool call results. (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603)) ## Other schema changes diff --git a/docs/specification/draft/server/tools.mdx b/docs/specification/draft/server/tools.mdx index 8ab4cf341..1b2f59ca4 100644 --- a/docs/specification/draft/server/tools.mdx +++ b/docs/specification/draft/server/tools.mdx @@ -233,21 +233,32 @@ Tool results may contain [**structured**](#structured-content) or **unstructured #### Linked Resources [Resources](/specification/draft/server/resources) **MAY** be linked, to provide additional context -or data, behind a URI that can be subscribed to or fetched again by the client later: +or data, behind a URI that can be subscribed to or fetched by the client: +```json +{ + "type": "linked_resource", + "uri": "file:///project/src/main.rs", + "name": "main.rs", + "description": "Primary application entry point", + "mimeType": "text/x-rust" +} +``` + +Linked resources returned by tools are not guaranteed to appear in the results of a `resources/list` request. #### 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: +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}" } } ``` diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index 66b001637..a409c8ef1 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -646,7 +646,7 @@ export interface PromptMessage { * */ export interface LinkedResource extends Resource { - type: "linkedresource"; + type: "linked_resource"; } /** From b88a8075e661157b007d14dd82cfb26c58f3bdab Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Thu, 5 Jun 2025 11:25:25 -0400 Subject: [PATCH 09/13] generate schema.json --- schema/draft/schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 4f514562b..3e909c762 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -1018,7 +1018,7 @@ "type": "integer" }, "type": { - "const": "linkedresource", + "const": "linked_resource", "type": "string" }, "uri": { From 2559ad4785bb1a2d8a8ab482f900f82f5578965b Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Thu, 5 Jun 2025 13:23:40 -0400 Subject: [PATCH 10/13] update schema.ts comment --- schema/draft/schema.json | 2 +- schema/draft/schema.ts | 7 ++----- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/schema/draft/schema.json b/schema/draft/schema.json index 3e909c762..cc938a10d 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -995,7 +995,7 @@ "type": "object" }, "LinkedResource": { - "description": "A reference to a resource descriptor, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render linked resources for the benefit\nof the LLM and/or the user.", + "description": "A resource that the server is capable of reading, embedded into a prompt or tool call result.\n\nNote: linked resources are not guaranteed to appear in the results of `resources/list` requests.", "properties": { "annotations": { "$ref": "#/definitions/Annotations", diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index a409c8ef1..ba652bdc6 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -638,12 +638,9 @@ export interface PromptMessage { } /** + * A resource that the server is capable of reading, embedded into a prompt or tool call result. * - * A reference to a resource descriptor, embedded into a prompt or tool call result. - * - * It is up to the client how best to render linked resources for the benefit - * of the LLM and/or the user. - * + * Note: linked resources are not guaranteed to appear in the results of `resources/list` requests. */ export interface LinkedResource extends Resource { type: "linked_resource"; From 70868f9e3c26526d9e04f47e90dbc558b1decd77 Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Thu, 5 Jun 2025 13:39:33 -0400 Subject: [PATCH 11/13] rebase, format --- docs/specification/draft/server/tools.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/specification/draft/server/tools.mdx b/docs/specification/draft/server/tools.mdx index 1b2f59ca4..f8bcc703e 100644 --- a/docs/specification/draft/server/tools.mdx +++ b/docs/specification/draft/server/tools.mdx @@ -245,7 +245,10 @@ or data, behind a URI that can be subscribed to or fetched by the client: } ``` -Linked resources returned by tools are not guaranteed to appear in the results of a `resources/list` request. + + Linked resources returned by tools are not guaranteed to appear in the results + of a `resources/list` request. + #### Embedded Resources From 4e6e4c600d69b2548eafad77f16e83fc05513a34 Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Mon, 9 Jun 2025 23:41:19 -0400 Subject: [PATCH 12/13] fix changelog link --- docs/specification/draft/changelog.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 000af4342..03ccb1287 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -21,7 +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 **[linked resources](http://localhost:3001/specification/draft/server/tools#linked-resources)** in tool call results. (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603)) +6. Added support for **[linked resources](/specification/draft/server/tools#linked-resources)** in + tool call results. (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603)) ## Other schema changes From bfbd362bb939b4c9cd82eb5a68b1bd74dcce44cf Mon Sep 17 00:00:00 2001 From: Basil Hosmer Date: Tue, 10 Jun 2025 12:26:05 -0400 Subject: [PATCH 13/13] LinkedResource -> ResourceLink --- docs/specification/draft/changelog.mdx | 2 +- docs/specification/draft/server/tools.mdx | 12 ++-- schema/draft/schema.json | 82 +++++++++++------------ schema/draft/schema.ts | 10 +-- 4 files changed, 53 insertions(+), 53 deletions(-) diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 03ccb1287..245a00ce9 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -21,7 +21,7 @@ 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 **[linked resources](/specification/draft/server/tools#linked-resources)** in +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 diff --git a/docs/specification/draft/server/tools.mdx b/docs/specification/draft/server/tools.mdx index f8bcc703e..c8dcf28ab 100644 --- a/docs/specification/draft/server/tools.mdx +++ b/docs/specification/draft/server/tools.mdx @@ -230,14 +230,14 @@ Tool results may contain [**structured**](#structured-content) or **unstructured } ``` -#### Linked Resources +#### Resource Links -[Resources](/specification/draft/server/resources) **MAY** be linked, to provide additional context -or data, behind a URI that can be subscribed to or fetched by the client: +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": "linked_resource", + "type": "resource_link", "uri": "file:///project/src/main.rs", "name": "main.rs", "description": "Primary application entry point", @@ -246,13 +246,13 @@ or data, behind a URI that can be subscribed to or fetched by the client: ``` - Linked resources returned by tools are not guaranteed to appear in the results + Resource links returned by tools are not guaranteed to appear in the results of a `resources/list` request. #### Embedded Resources -[Resources](/specification/draft/server/resources) **MAY** be embedded, to provide additional context +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 diff --git a/schema/draft/schema.json b/schema/draft/schema.json index cc938a10d..22ed285b1 100644 --- a/schema/draft/schema.json +++ b/schema/draft/schema.json @@ -406,7 +406,7 @@ "$ref": "#/definitions/AudioContent" }, { - "$ref": "#/definitions/LinkedResource" + "$ref": "#/definitions/ResourceLink" }, { "$ref": "#/definitions/EmbeddedResource" @@ -994,46 +994,6 @@ ], "type": "object" }, - "LinkedResource": { - "description": "A resource that the server is capable of reading, embedded into a prompt or tool call result.\n\nNote: linked resources are not guaranteed to appear in the results of `resources/list` requests.", - "properties": { - "annotations": { - "$ref": "#/definitions/Annotations", - "description": "Optional annotations for the client." - }, - "description": { - "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", - "type": "string" - }, - "mimeType": { - "description": "The MIME type of this resource, if known.", - "type": "string" - }, - "name": { - "description": "A human-readable name for this resource.\n\nThis can be used by clients to populate UI elements.", - "type": "string" - }, - "size": { - "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", - "type": "integer" - }, - "type": { - "const": "linked_resource", - "type": "string" - }, - "uri": { - "description": "The URI of this resource.", - "format": "uri", - "type": "string" - } - }, - "required": [ - "name", - "type", - "uri" - ], - "type": "object" - }, "ListPromptsRequest": { "description": "Sent from the client to request a list of prompts and prompt templates the server has.", "properties": { @@ -1772,6 +1732,46 @@ ], "type": "object" }, + "ResourceLink": { + "description": "A resource that the server is capable of reading, included in a prompt or tool call result.\n\nNote: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.", + "properties": { + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "A human-readable name for this resource.\n\nThis can be used by clients to populate UI elements.", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" + }, + "type": { + "const": "resource_link", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "name", + "type", + "uri" + ], + "type": "object" + }, "ResourceListChangedNotification": { "description": "An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client.", "properties": { diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts index ba652bdc6..ec5340a99 100644 --- a/schema/draft/schema.ts +++ b/schema/draft/schema.ts @@ -638,12 +638,12 @@ export interface PromptMessage { } /** - * A resource that the server is capable of reading, embedded into a prompt or tool call result. + * A resource that the server is capable of reading, included in a prompt or tool call result. * - * Note: linked resources are not guaranteed to appear in the results of `resources/list` requests. + * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests. */ -export interface LinkedResource extends Resource { - type: "linked_resource"; +export interface ResourceLink extends Resource { + type: "resource_link"; } /** @@ -966,7 +966,7 @@ export type ContentBlock = | TextContent | ImageContent | AudioContent - | LinkedResource + | ResourceLink | EmbeddedResource; /**