Merge pull request modelcontextprotocol#891 from modelcontextprotocol/feat/resource-annotations

dsp-ant · web-flow · commit 3cbdc467ecef · 2025-07-15T23:01:50.000+01:00
Include Annotations for Content types and Resources in documentation
diff --git a/docs/specification/2025-06-18/server/prompts.mdx b/docs/specification/2025-06-18/server/prompts.mdx
@@ -186,6 +186,12 @@ Messages in a prompt can contain:
 - `role`: Either "user" or "assistant" to indicate the speaker
 - `content`: One of the following content types:
 
+<Note>
+  All content types in prompt messages support optional
+  [annotations](/specification/2025-06-18/server/resources#annotations) for
+  metadata about audience, priority, and modification times.
+</Note>
+
 #### Text Content
 
 Text content represents plain text messages:
diff --git a/docs/specification/2025-06-18/server/resources.mdx b/docs/specification/2025-06-18/server/resources.mdx
@@ -305,6 +305,36 @@ Resources can contain either text or binary data:
 }
 ```
 
+### Annotations
+
+Resources, resource templates and content blocks support optional annotations that provide hints to clients about how to use or display the resource:
+
+- **`audience`**: An array indicating the intended audience(s) for this resource. Valid values are `"user"` and `"assistant"`. For example, `["user", "assistant"]` indicates content useful for both.
+- **`priority`**: A number from 0.0 to 1.0 indicating the importance of this resource. A value of 1 means "most important" (effectively required), while 0 means "least important" (entirely optional).
+- **`lastModified`**: An ISO 8601 formatted timestamp indicating when the resource was last modified (e.g., `"2025-01-12T15:00:58Z"`).
+
+Example resource with annotations:
+
+```json
+{
+  "uri": "file:///project/README.md",
+  "name": "README.md",
+  "title": "Project Documentation",
+  "mimeType": "text/markdown",
+  "annotations": {
+    "audience": ["user"],
+    "priority": 0.8,
+    "lastModified": "2025-01-12T15:00:58Z"
+  }
+}
+```
+
+Clients can use these annotations to:
+
+- Filter resources based on their intended audience
+- Prioritize which resources to include in context
+- Display modification times or sort by recency
+
 ## Common URI Schemes
 
 The protocol defines several standard URI schemes. This list not
diff --git a/docs/specification/2025-06-18/server/tools.mdx b/docs/specification/2025-06-18/server/tools.mdx
@@ -203,6 +203,14 @@ Tool results may contain [**structured**](#structured-content) or **unstructured
 
 **Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
 
+<Note>
+  All content types (text, image, audio, resource links, and embedded resources)
+  support optional
+  [annotations](/specification/2025-06-18/server/resources#annotations) that
+  provide metadata about audience, priority, and modification times. This is the
+  same annotation format used by resources and prompts.
+</Note>
+
 #### Text Content
 
 ```json
@@ -219,9 +227,16 @@ Tool results may contain [**structured**](#structured-content) or **unstructured
   "type": "image",
   "data": "base64-encoded-data",
   "mimeType": "image/png"
+  "annotations": {
+    "audience": ["user"],
+    "priority": 0.9
+  }
+
 }
 ```
 
+This example demonstrates the use of an optional Annotation.
+
 #### Audio Content
 
 ```json
@@ -243,10 +258,16 @@ or data. In this case, the tool will return a URI that can be subscribed to or f
   "uri": "file:///project/src/main.rs",
   "name": "main.rs",
   "description": "Primary application entry point",
-  "mimeType": "text/x-rust"
+  "mimeType": "text/x-rust",
+  "annotations": {
+    "audience": ["assistant"],
+    "priority": 0.9
+  }
 }
 ```
 
+Resource links support the same [Resource annotations](/specification/2025-06-18/server/resources#annotations) as regular resources to help clients understand how to use them.
+
 <Info>
   Resource links returned by tools are not guaranteed to appear in the results
   of a `resources/list` request.
@@ -264,11 +285,18 @@ or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers t
     "uri": "file:///project/src/main.rs",
     "title": "Project Rust Main File",
     "mimeType": "text/x-rust",
-    "text": "fn main() {\n    println!(\"Hello world!\");\n}"
+    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
+    "annotations": {
+      "audience": ["user", "assistant"],
+      "priority": 0.7,
+      "lastModified": "2025-05-03T14:30:00Z"
+    }
   }
 }
 ```
 
+Embedded resources support the same [Resource annotations](/specification/2025-06-18/server/resources#annotations) as regular resources to help clients understand how to use them.
+
 #### Structured Content
 
 **Structured** content is returned as a JSON object in the `structuredContent` field of a result.
diff --git a/docs/specification/draft/server/prompts.mdx b/docs/specification/draft/server/prompts.mdx
@@ -186,6 +186,12 @@ Messages in a prompt can contain:
 - `role`: Either "user" or "assistant" to indicate the speaker
 - `content`: One of the following content types:
 
+<Note>
+  All content types in prompt messages support optional
+  [annotations](/specification/2025-06-18/server/resources#annotations) for
+  metadata about audience, priority, and modification times.
+</Note>
+
 #### Text Content
 
 Text content represents plain text messages:
diff --git a/docs/specification/draft/server/resources.mdx b/docs/specification/draft/server/resources.mdx
@@ -305,6 +305,36 @@ Resources can contain either text or binary data:
 }
 ```
 
+### Annotations
+
+Resources, resource templates and content blocks support optional annotations that provide hints to clients about how to use or display the resource:
+
+- **`audience`**: An array indicating the intended audience(s) for this resource. Valid values are `"user"` and `"assistant"`. For example, `["user", "assistant"]` indicates content useful for both.
+- **`priority`**: A number from 0.0 to 1.0 indicating the importance of this resource. A value of 1 means "most important" (effectively required), while 0 means "least important" (entirely optional).
+- **`lastModified`**: An ISO 8601 formatted timestamp indicating when the resource was last modified (e.g., `"2025-01-12T15:00:58Z"`).
+
+Example resource with annotations:
+
+```json
+{
+  "uri": "file:///project/README.md",
+  "name": "README.md",
+  "title": "Project Documentation",
+  "mimeType": "text/markdown",
+  "annotations": {
+    "audience": ["user"],
+    "priority": 0.8,
+    "lastModified": "2025-01-12T15:00:58Z"
+  }
+}
+```
+
+Clients can use these annotations to:
+
+- Filter resources based on their intended audience
+- Prioritize which resources to include in context
+- Display modification times or sort by recency
+
 ## Common URI Schemes
 
 The protocol defines several standard URI schemes. This list not
diff --git a/docs/specification/draft/server/tools.mdx b/docs/specification/draft/server/tools.mdx
@@ -203,6 +203,14 @@ Tool results may contain [**structured**](#structured-content) or **unstructured
 
 **Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
 
+<Note>
+  All content types (text, image, audio, resource links, and embedded resources)
+  support optional
+  [annotations](/specification/draft/server/resources#annotations) that provide
+  metadata about audience, priority, and modification times. This is the same
+  annotation format used by resources and prompts.
+</Note>
+
 #### Text Content
 
 ```json
@@ -218,7 +226,11 @@ Tool results may contain [**structured**](#structured-content) or **unstructured
 {
   "type": "image",
   "data": "base64-encoded-data",
-  "mimeType": "image/png"
+  "mimeType": "image/png",
+  "annotations": {
+    "audience": ["user"],
+    "priority": 0.9
+  }
 }
 ```
 
@@ -247,6 +259,8 @@ or data. In this case, the tool will return a URI that can be subscribed to or f
 }
 ```
 
+Resource links support the same [Resource annotations](/specification/draft/server/resources#annotations) as regular resources to help clients understand how to use them.
+
 <Info>
   Resource links returned by tools are not guaranteed to appear in the results
   of a `resources/list` request.
@@ -264,11 +278,18 @@ or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers t
     "uri": "file:///project/src/main.rs",
     "title": "Project Rust Main File",
     "mimeType": "text/x-rust",
-    "text": "fn main() {\n    println!(\"Hello world!\");\n}"
+    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
+    "annotations": {
+      "audience": ["user", "assistant"],
+      "priority": 0.7,
+      "lastModified": "2025-05-03T14:30:00Z"
+    }
   }
 }
 ```
 
+Embedded resources support the same [Resource annotations](/specification/draft/server/resources#annotations) as regular resources to help clients understand how to use them.
+
 #### Structured Content
 
 **Structured** content is returned as a JSON object in the `structuredContent` field of a result.
