Refactor ToolAnnotations:

- simplify data model for operational properties, to facilitate extensibility (at the cost of correctness by construction)
- added documentation for `annotations` property in tool definitions
- added language in `Security and Trust & Safety` section re trusting annotations

Author: bhosmer-ant

docs/specification/draft/_index.md

@@ -102,7 +102,9 @@ considerations that all implementors must carefully address.
 3. **Tool Safety**
 
    - Tools represent arbitrary code execution and must be treated with appropriate
-     caution
+     caution. 
+     - In particular, descriptions of tool behavior such as annotations should be 
+     considered untrusted, unless obtained from a trusted server.
    - Hosts must obtain explicit user consent before invoking any tool
    - Users should understand what each tool does before authorizing its use
 

docs/specification/draft/server/tools.md

@@ -181,6 +181,9 @@ A tool definition includes:
 - `name`: Unique identifier for the tool
 - `description`: Human-readable description of functionality
 - `inputSchema`: JSON Schema defining expected parameters
+- `annotations`: optional properties describing tool behavior
+
+{{< callout type="warning" >}} For trust & safety and security, clients **MUST** consider tool annotations to be untrusted unless they come from trusted servers.
 
 ### Tool Result
 

schema/draft/schema.json

@@ -1985,45 +1985,22 @@
             "type": "object"
         },
         "ToolAnnotations": {
-            "description": "Additional properties describing a Tool to clients.",
+            "description": "Additional properties describing a Tool to clients.\n\nNOTE: all properties in ToolAnnotations are **hints**. \nThey are not guaranteed to provide a faithful description of \ntool behavior (including descriptive properties like `title`).\n\nClients should never make tool use decisions based on ToolAnnotations\nreceived from untrusted servers.",
             "properties": {
-                "effectHints": {
-                    "anyOf": [
-                        {
-                            "properties": {
-                                "readOnly": {
-                                    "const": true,
-                                    "type": "boolean"
-                                }
-                            },
-                            "required": [
-                                "readOnly"
-                            ],
-                            "type": "object"
-                        },
-                        {
-                            "properties": {
-                                "destructive": {
-                                    "type": "boolean"
-                                },
-                                "idempotent": {
-                                    "type": "boolean"
-                                },
-                                "readOnly": {
-                                    "const": false,
-                                    "type": "boolean"
-                                }
-                            },
-                            "required": [
-                                "readOnly"
-                            ],
-                            "type": "object"
-                        }
-                    ],
-                    "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 }"
+                "destructiveHint": {
+                    "description": "If true, the tool may perform destructive updates to its environment.\nIf false, the tool performs only additive updates.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: true",
+                    "type": "boolean"
+                },
+                "idempotentHint": {
+                    "description": "If true, calling the tool repeatedly with the same arguments \nwill have no additional effect on the its environment.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: false",
+                    "type": "boolean"
                 },
                 "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.",
+                    "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\nDefault: true",
+                    "type": "boolean"
+                },
+                "readOnlyHint": {
+                    "description": "If true, the tool does not modify its environment.\n\nDefault: false",
                     "type": "boolean"
                 },
                 "title": {

schema/draft/schema.ts

@@ -698,6 +698,13 @@ export interface ToolListChangedNotification extends Notification {
 
 /**
  * Additional properties describing a Tool to clients.
+ * 
+ * NOTE: all properties in ToolAnnotations are **hints**. 
+ * They are not guaranteed to provide a faithful description of 
+ * tool behavior (including descriptive properties like `title`).
+ * 
+ * Clients should never make tool use decisions based on ToolAnnotations
+ * received from untrusted servers.
  */
 export interface ToolAnnotations {
   /**
@@ -706,36 +713,39 @@ export interface ToolAnnotations {
   title?: string;
 
   /**
-   * Describes the effects a tool may have on its environment.
+   * If true, the tool does not modify its environment.
    * 
-   * NOTE: these properties are **hints**. They do not guarantee tool behavior.
-   *
-   * 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;
-      };
+   * Default: false
+   */
+  readOnlyHint?: boolean;
+
+  /**
+   * If true, the tool may perform destructive updates to its environment.
+   * If false, the tool performs only additive updates.
+   * 
+   * (This property is meaningful only when `readOnlyHint == false`)
+   * 
+   * Default: true
+   */
+  destructiveHint?: boolean;
+
+  /**
+   * If true, calling the tool repeatedly with the same arguments 
+   * will have no additional effect on the its environment.
+   * 
+   * (This property is meaningful only when `readOnlyHint == false`)
+   * 
+   * Default: false
+   */
+  idempotentHint?: 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.
+   * Default: true
    */
   openWorldHint?: boolean;
 }