Merge pull request modelcontextprotocol#185 from modelcontextprotocol/basil/tool-annotation

ToolAnnotations

Author: jspahrsummers

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,10 @@ 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. {{< /callout >}}
 
 ### Tool Result
 

schema/draft/schema.json

@@ -1995,8 +1995,12 @@
         "Tool": {
             "description": "Definition for a tool the client can call.",
             "properties": {
+                "annotations": {
+                    "$ref": "#/definitions/ToolAnnotations",
+                    "description": "Optional additional tool information."
+                },
                 "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": {
@@ -2037,6 +2041,32 @@
             ],
             "type": "object"
         },
+        "ToolAnnotations": {
+            "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": {
+                "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\nDefault: true",
+                    "type": "boolean"
+                },
+                "readOnlyHint": {
+                    "description": "If true, the tool does not modify its environment.\n\nDefault: false",
+                    "type": "boolean"
+                },
+                "title": {
+                    "description": "A human-readable title for the tool.",
+                    "type": "string"
+                }
+            },
+            "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

@@ -713,6 +713,60 @@ export interface ToolListChangedNotification extends Notification {
   method: "notifications/tools/list_changed";
 }
 
+/**
+ * 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 {
+  /**
+   * A human-readable title for the tool.
+   */
+  title?: string;
+
+  /**
+   * If true, the tool does not modify its environment.
+   * 
+   * 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.
+   * 
+   * Default: true
+   */
+  openWorldHint?: boolean;
+}
+
 /**
  * Definition for a tool the client can call.
  */
@@ -721,10 +775,14 @@ export interface Tool {
    * The name of the 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;
+
   /**
    * A JSON Schema object defining the expected parameters for the tool.
    */
@@ -733,6 +791,11 @@ export interface Tool {
     properties?: { [key: string]: object };
     required?: string[];
   };
+
+  /**
+   * Optional additional tool information.
+   */
+  annotations?: ToolAnnotations;
 }
 
 /* Logging */
@@ -850,14 +913,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.
@@ -910,7 +973,6 @@ export interface ImageContent {
   annotations?: Annotations;
 }
 
-
 /**
  * Audio provided to or from an LLM.
  */
@@ -935,7 +997,6 @@ export interface AudioContent {
   annotations?: Annotations;
 }
 
-
 /**
  * The server's preferences for model selection, requested of the client during sampling.
  *