Remove category and extraInfo, add openWorld and caption, add clarification to Tool.description

Author: bhosmer-ant

schema/draft/schema.json

@@ -1938,8 +1938,12 @@
         "Tool": {
             "description": "Definition for a tool the client can call.",
             "properties": {
+                "annotations": {
+                    "$ref": "#/definitions/ToolAnnotations",
+                    "description": "Annotations"
+                },
                 "description": {
-                    "description": "A human-readable description of the tool.",
+                    "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.",
                     "type": "string"
                 },
                 "inputSchema": {
@@ -1980,6 +1984,24 @@
             ],
             "type": "object"
         },
+        "ToolAnnotations": {
+            "description": "A tool annotation defines additional, optional properties that\ncharacterize the tool's behavior.",
+            "properties": {
+                "caption": {
+                    "description": "A succinct user-facing description of the tool.\n\nUnlike Tool.description, this is not intended for use as a \"hint\" to the model.",
+                    "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"
+                },
+                "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.",
+                    "type": "boolean"
+                }
+            },
+            "type": "object"
+        },
         "ToolListChangedNotification": {
             "description": "An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client.",
             "properties": {

schema/draft/schema.ts

@@ -696,6 +696,35 @@ export interface ToolListChangedNotification extends Notification {
   method: "notifications/tools/list_changed";
 }
 
+/**
+ * Optional, supplemental properties that characterize a tool's behavior.
+ */
+export interface ToolAnnotations {
+  /**
+   * 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.
+   *
+   * 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 is assumed to be true.
+   */
+  openWorld?: boolean;
+
+  /**
+   * A succinct user-facing description of the tool.
+   *
+   * Unlike Tool.description, this is not intended for use as a "hint" to the model.
+   */
+  caption?: string;
+}
+
 /**
  * Definition for a tool the client can call.
  */
@@ -706,8 +735,14 @@ export interface Tool {
   name: string;
   /**
    * A human-readable description of the tool.
+   *
+   * This 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.
    */
   description?: string;
+  /**
+   * Annotations
+   */
+  annotations?: ToolAnnotations;
   /**
    * A JSON Schema object defining the expected parameters for the tool.
    */