Merge pull request #3246 from olaservo/fix/tool-annotations

feat(everything): add tool-level annotations to get-annotated-message

src/everything/docs/structure.md

@@ -48,11 +48,14 @@ src/everything
      │   ├── get-sum.ts
      │   ├── get-tiny-image.ts
      │   ├── gzip-file-as-resource.ts
+     │   ├── simulate-research-query.ts
      │   ├── toggle-simulated-logging.ts
      │   ├── toggle-subscriber-updates.ts
      │   ├── trigger-elicitation-request.ts
+     │   ├── trigger-elicitation-request-async.ts
      │   ├── trigger-long-running-operation.ts
-     │   └── trigger-sampling-request.ts
+     │   ├── trigger-sampling-request.ts
+     │   └── trigger-sampling-request-async.ts
      └── transports
          ├── sse.ts
          ├── stdio.ts
@@ -129,7 +132,7 @@ src/everything
 - `echo.ts`
   - Registers an `echo` tool that takes a message and returns `Echo: {message}`.
 - `get-annotated-message.ts`
-  - Registers an `annotated-message` tool which demonstrates annotated content items by emitting a primary `text` message with `annotations` that vary by `messageType` (`"error" | "success" | "debug"`), and optionally includes an annotated `image` (tiny PNG) when `includeImage` is true.
+  - Registers a `get-annotated-message` tool which demonstrates content-level annotations. Emits a primary `text` message with content `annotations` (`priority`, `audience`) that vary by `messageType` (`"error" | "success" | "debug"`), and optionally includes an annotated `image` (tiny PNG) when `includeImage` is true. All tools in this server include tool-level annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
 - `get-env.ts`
   - Registers a `get-env` tool that returns the current process environment variables as formatted JSON text; useful for debugging configuration.
 - `get-resource-links.ts`
@@ -147,18 +150,24 @@ src/everything
     - `GZIP_MAX_FETCH_SIZE` (bytes, default 10 MiB)
     - `GZIP_MAX_FETCH_TIME_MILLIS` (ms, default 30000)
     - `GZIP_ALLOWED_DOMAINS` (comma-separated allowlist; empty means all domains allowed)
+- `simulate-research-query.ts`
+  - Registers a `simulate-research-query` task-based tool that demonstrates the MCP Tasks feature (SEP-1686). Simulates a multi-stage research operation with progress updates. If the query is marked as ambiguous and the client supports elicitation, it pauses mid-execution to request clarification via `elicitation/create`. Uses `server.experimental.tasks.registerToolTask()` with `execution: { taskSupport: "required" }`.
 - `trigger-elicitation-request.ts`
   - Registers a `trigger-elicitation-request` tool that sends an `elicitation/create` request to the client/LLM and returns the elicitation result.
+- `trigger-elicitation-request-async.ts`
+  - Registers a `trigger-elicitation-request-async` tool that demonstrates bidirectional MCP tasks for elicitation. Sends an elicitation request with task metadata, then polls the client's `tasks/get` endpoint for completion status before fetching the final result.
 - `trigger-sampling-request.ts`
   - Registers a `trigger-sampling-request` tool that sends a `sampling/createMessage` request to the client/LLM and returns the sampling result.
+- `trigger-sampling-request-async.ts`
+  - Registers a `trigger-sampling-request-async` tool that demonstrates bidirectional MCP tasks for sampling. Sends a sampling request with task metadata, then polls the client's `tasks/get` endpoint for completion status before fetching the final result.
 - `get-structured-content.ts`
   - Registers a `get-structured-content` tool that demonstrates structuredContent block responses.
 - `get-sum.ts`
-  - Registers an `get-sum` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result.
+  - Registers a `get-sum` tool with a Zod input schema that sums two numbers `a` and `b` and returns the result.
 - `get-tiny-image.ts`
   - Registers a `get-tiny-image` tool, which returns a tiny PNG MCP logo as an `image` content item, along with surrounding descriptive `text` items.
 - `trigger-long-running-operation.ts`
-  - Registers a `long-running-operation` tool that simulates a long-running task over a specified `duration` (seconds) and number of `steps`; emits `notifications/progress` updates when the client supplies a `progressToken`.
+  - Registers a `trigger-long-running-operation` tool that simulates a long-running task over a specified `duration` (seconds) and number of `steps`; emits `notifications/progress` updates when the client supplies a `progressToken`.
 - `toggle-simulated-logging.ts`
   - Registers a `toggle-simulated-logging` tool, which starts or stops simulated logging for the invoking session.
 - `toggle-subscriber-updates.ts`

src/everything/tools/echo.ts

@@ -13,6 +13,12 @@ const config = {
   title: "Echo Tool",
   description: "Echoes back the input string",
   inputSchema: EchoSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-annotated-message.ts

@@ -21,6 +21,12 @@ const config = {
   description:
     "Demonstrates how annotations can be used to provide metadata about content.",
   inputSchema: GetAnnotatedMessageSchema,
+  annotations: {
+    readOnlyHint: true,       // This tool only returns data, no side effects
+    destructiveHint: false,   // Does not delete or modify anything
+    idempotentHint: true,     // Same input always produces same output
+    openWorldHint: false,     // Does not interact with external systems
+  },
 };
 
 /**

src/everything/tools/get-env.ts

@@ -8,6 +8,12 @@ const config = {
   description:
     "Returns all environment variables, helpful for debugging MCP server configuration",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-resource-links.ts

@@ -25,6 +25,12 @@ const config = {
   description:
     "Returns up to ten resource links that reference different types of resources",
   inputSchema: GetResourceLinksSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-resource-reference.ts

@@ -28,6 +28,12 @@ const config = {
   title: "Get Resource Reference Tool",
   description: "Returns a resource reference that can be used by MCP clients",
   inputSchema: GetResourceReferenceSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-roots-list.ts

@@ -9,6 +9,12 @@ const config = {
   description:
     "Lists the current MCP roots provided by the client. Demonstrates the roots protocol capability even though this server doesn't access files.",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-structured-content.ts

@@ -27,6 +27,12 @@ const config = {
     "Returns structured content along with an output schema for client data validation",
   inputSchema: GetStructuredContentInputSchema,
   outputSchema: GetStructuredContentOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-sum.ts

@@ -14,6 +14,12 @@ const config = {
   title: "Get Sum Tool",
   description: "Returns the sum of two numbers",
   inputSchema: GetSumSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/get-tiny-image.ts

@@ -11,6 +11,12 @@ const config = {
   title: "Get Tiny Image Tool",
   description: "Returns a tiny MCP logo image.",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/gzip-file-as-resource.ts

@@ -47,6 +47,12 @@ const config = {
   description:
     "Compresses a single file using gzip compression. Depending upon the selected output type, returns either the compressed data as a gzipped resource or a resource link, allowing it to be downloaded in a subsequent request during the current session.",
   inputSchema: GZipFileAsResourceSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
 };
 
 /**

src/everything/tools/simulate-research-query.ts

@@ -255,6 +255,12 @@ export const registerSimulateResearchQueryTool = (server: McpServer) => {
         "If 'ambiguous' is true and client supports elicitation, sends an elicitation request for clarification.",
       inputSchema: SimulateResearchQuerySchema,
       execution: { taskSupport: "required" },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
     },
     {
       /**

src/everything/tools/toggle-simulated-logging.ts

@@ -11,6 +11,12 @@ const config = {
   title: "Toggle Simulated Logging",
   description: "Toggles simulated, random-leveled logging on or off.",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
 };
 
 // Track enabled clients by session id

src/everything/tools/toggle-subscriber-updates.ts

@@ -11,6 +11,12 @@ const config = {
   title: "Toggle Subscriber Updates",
   description: "Toggles simulated resource subscription updates on or off.",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
 };
 
 // Track enabled clients by session id

src/everything/tools/trigger-elicitation-request-async.ts

@@ -11,6 +11,12 @@ const config = {
     "Demonstrates bidirectional MCP tasks where the server sends an elicitation request and " +
     "the client handles user input asynchronously, allowing the server to poll for completion.",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
 };
 
 // Poll interval in milliseconds

src/everything/tools/trigger-elicitation-request.ts

@@ -10,6 +10,12 @@ const config = {
   title: "Trigger Elicitation Request Tool",
   description: "Trigger a Request from the Server for User Elicitation",
   inputSchema: {},
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/trigger-long-running-operation.ts

@@ -17,6 +17,12 @@ const config = {
   title: "Trigger Long Running Operation Tool",
   description: "Demonstrates a long running operation with progress updates.",
   inputSchema: TriggerLongRunningOperationSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
 };
 
 /**

src/everything/tools/trigger-sampling-request-async.ts

@@ -23,6 +23,12 @@ const config = {
     "Demonstrates bidirectional MCP tasks where the server sends a request and the client " +
     "executes it asynchronously, allowing the server to poll for progress and results.",
   inputSchema: TriggerSamplingRequestAsyncSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
 };
 
 // Poll interval in milliseconds

src/everything/tools/trigger-sampling-request.ts

@@ -21,6 +21,12 @@ const config = {
   title: "Trigger Sampling Request Tool",
   description: "Trigger a Request from the Server for LLM Sampling",
   inputSchema: TriggerSamplingRequestSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
 };
 
 /**