Refactor tool annotations to add effectHints property

bhosmer-ant · claude · bhosmer-ant · commit 3a96a59ce980 · 2025-03-21T10:45:45.000-04:00
- Replace readOnly property with more descriptive effectHints object - Rename openWorld to openWorldHint to clarify it's a hint - Add additional tool effect properties (destructive, idempotent) - Clarify these properties are hints only in documentation - Remove unused DisplayAnnotations interface 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/schema/draft/schema.json b/schema/draft/schema.json
@@ -464,35 +464,6 @@
             "description": "An opaque token used to represent a cursor for pagination.",
             "type": "string"
         },
-        "DisplayAnnotations": {
-            "description": "Annotations that provide display-facing information to the client.",
-            "properties": {
-                "icon": {
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
-                        },
-                        "data": {
-                            "type": "string"
-                        }
-                    },
-                    "required": [
-                        "contentType",
-                        "data"
-                    ],
-                    "type": "object"
-                },
-                "icon_url": {
-                    "description": "A URL from which a client can fetch an icon to represent this object.",
-                    "type": "string"
-                },
-                "title": {
-                    "description": "A human-readable title for the object or data.",
-                    "type": "string"
-                }
-            },
-            "type": "object"
-        },
         "EmbeddedResource": {
             "description": "The contents of a resource, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render embedded resources for the benefit\nof the LLM and/or the user.",
             "properties": {
@@ -1969,7 +1940,7 @@
             "properties": {
                 "annotations": {
                     "$ref": "#/definitions/ToolAnnotations",
-                    "description": "Annotations"
+                    "description": "Optional additional tool information."
                 },
                 "description": {
                     "description": "A human-readable description of the tool.\n\nThis can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a \"hint\" to the model.",
@@ -2014,37 +1985,49 @@
             "type": "object"
         },
         "ToolAnnotations": {
-            "description": "Annotations that provide display-facing and operational information for a Tool.",
+            "description": "Additional properties describing a Tool to clients.",
             "properties": {
-                "icon": {
-                    "properties": {
-                        "contentType": {
-                            "type": "string"
+                "effectHints": {
+                    "anyOf": [
+                        {
+                            "properties": {
+                                "readOnly": {
+                                    "const": true,
+                                    "type": "boolean"
+                                }
+                            },
+                            "required": [
+                                "readOnly"
+                            ],
+                            "type": "object"
                         },
-                        "data": {
-                            "type": "string"
+                        {
+                            "properties": {
+                                "destructive": {
+                                    "type": "boolean"
+                                },
+                                "idempotent": {
+                                    "type": "boolean"
+                                },
+                                "readOnly": {
+                                    "const": false,
+                                    "type": "boolean"
+                                }
+                            },
+                            "required": [
+                                "readOnly"
+                            ],
+                            "type": "object"
                         }
-                    },
-                    "required": [
-                        "contentType",
-                        "data"
                     ],
-                    "type": "object"
-                },
-                "icon_url": {
-                    "description": "A URL from which a client can fetch an icon to represent this object.",
-                    "type": "string"
-                },
-                "openWorld": {
-                    "description": "If true, this tool may interact with an open set of \"external\"\nentities, e.g. by making web queries.\n\nIf not set, this is assumed to be true.",
-                    "type": "boolean"
+                    "description": "Describes the effects a tool may have on its environment.\n\nNOTE: these properties are **hints**. They do not guarantee tool behavior.\n\nIf not set, this property is assumed to have the value:\n { readOnly: false, destructive: true, idempotent: false }"
                 },
-                "readOnly": {
-                    "description": "If true, this tool does not perform writes or updates,\nor otherwise change server-side state in ways that would\nbe visible in subsequent tool calls.\n\nIf not set, this is assumed to be false.",
+                "openWorldHint": {
+                    "description": "If true, this tool may interact with an \"open world\" of external\nentities. If false, the tool's domain of interaction is closed.\nFor example, the world of a web search tool is open, whereas that\nof a memory tool is not.\n\nNOTE: this property is a **hint**. It does not guarantee tool behavior.\n\nIf not set, this is assumed to be true.",
                     "type": "boolean"
                 },
                 "title": {
-                    "description": "A human-readable title for the object or data.",
+                    "description": "A human-readable title for the tool.",
                     "type": "string"
                 }
             },
diff --git a/schema/draft/schema.ts b/schema/draft/schema.ts
@@ -697,45 +697,47 @@ export interface ToolListChangedNotification extends Notification {
 }
 
 /**
- * Annotations that provide display-facing information to the client.
+ * Additional properties describing a Tool to clients.
  */
-export interface DisplayAnnotations {
+export interface ToolAnnotations {
   /**
-   * A human-readable title for the object or data.
+   * A human-readable title for the tool.
    */
   title?: string;
 
-  icon?: {
-    data: string; // base64-encoded image data
-    contentType: string; // MIME type of the image
-  };
-
-  /**
-   * A URL from which a client can fetch an icon to represent this object.
-   */
-  icon_url?: string;
-}
-
-/**
- * Annotations that provide display-facing and operational information for a Tool.
- */
-export interface ToolAnnotations extends DisplayAnnotations {
   /**
-   * If true, this tool does not perform writes or updates,
-   * or otherwise change server-side state in ways that would
-   * be visible in subsequent tool calls.
+   * Describes the effects a tool may have on its environment.
+   * 
+   * NOTE: these properties are **hints**. They do not guarantee tool behavior.
    *
-   * If not set, this is assumed to be false.
-   */
-  readOnly?: boolean;
-
-  /**
-   * If true, this tool may interact with an open set of "external"
-   * entities, e.g. by making web queries.
+   * If not set, this property is assumed to have the value:
+   *  { readOnly: false, destructive: true, idempotent: false }
+   */
+  effectHints?:
+    | {
+        /* Tool is read-only. */
+        readOnly: true;
+      }
+    | {
+        /* Tool is read-write. */
+        readOnly: false;
+        /* If true, tool may perform destructive updates to its environment, as opposed to only additive updates. Default: true */
+        destructive?: boolean;
+        /* If true, repeated calls with the same arguments will have no additional effects. Default: false */
+        idempotent?: boolean;
+      };
+
+  /**
+   * If true, this tool may interact with an "open world" of external
+   * entities. If false, the tool's domain of interaction is closed.
+   * For example, the world of a web search tool is open, whereas that
+   * of a memory tool is not.
    *
+   * NOTE: this property is a **hint**. It does not guarantee tool behavior.
+   * 
    * If not set, this is assumed to be true.
    */
-  openWorld?: boolean;
+  openWorldHint?: boolean;
 }
 
 /**
@@ -764,7 +766,7 @@ export interface Tool {
   };
 
   /**
-   * Annotations
+   * Optional additional tool information.
    */
   annotations?: ToolAnnotations;
 }
@@ -884,14 +886,14 @@ export interface SamplingMessage {
 export interface Annotations {
   /**
    * Describes who the intended customer of this object or data is.
-   * 
+   *
    * It can include multiple entries to indicate content useful for multiple audiences (e.g., `["user", "assistant"]`).
    */
   audience?: Role[];
 
   /**
    * Describes how important this data is for operating the server.
-   * 
+   *
    * A value of 1 means "most important," and indicates that the data is
    * effectively required, while 0 means "least important," and indicates that
    * the data is entirely optional.
@@ -944,7 +946,6 @@ export interface ImageContent {
   annotations?: Annotations;
 }
 
-
 /**
  * Audio provided to or from an LLM.
  */
@@ -969,7 +970,6 @@ export interface AudioContent {
   annotations?: Annotations;
 }
 
-
 /**
  * The server's preferences for model selection, requested of the client during sampling.
  *
