feat: Add tool annotations for improved LLM tool understanding

src/server.ts

@@ -41,7 +41,14 @@ export async function createServerWithTools(options: Options): Promise<Server> {
   });
 
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: tools.map((tool) => tool.schema) };
+    return {
+      tools: tools.map((tool) => ({
+        name: tool.schema.name,
+        description: tool.schema.description,
+        inputSchema: tool.schema.inputSchema,
+        annotations: tool.schema.annotations,
+      })),
+    };
   });
 
   server.setRequestHandler(ListResourcesRequestSchema, async () => {

src/tools/common.ts

@@ -17,6 +17,10 @@ export const navigate: ToolFactory = (snapshot) => ({
     name: NavigateTool.shape.name.value,
     description: NavigateTool.shape.description.value,
     inputSchema: zodToJsonSchema(NavigateTool.shape.arguments),
+    annotations: {
+      title: "Navigate",
+      destructiveHint: true,
+    },
   },
   handle: async (context, params) => {
     const { url } = NavigateTool.shape.arguments.parse(params);
@@ -40,6 +44,10 @@ export const goBack: ToolFactory = (snapshot) => ({
     name: GoBackTool.shape.name.value,
     description: GoBackTool.shape.description.value,
     inputSchema: zodToJsonSchema(GoBackTool.shape.arguments),
+    annotations: {
+      title: "Go Back",
+      destructiveHint: true,
+    },
   },
   handle: async (context) => {
     await context.sendSocketMessage("browser_go_back", {});
@@ -62,6 +70,10 @@ export const goForward: ToolFactory = (snapshot) => ({
     name: GoForwardTool.shape.name.value,
     description: GoForwardTool.shape.description.value,
     inputSchema: zodToJsonSchema(GoForwardTool.shape.arguments),
+    annotations: {
+      title: "Go Forward",
+      destructiveHint: true,
+    },
   },
   handle: async (context) => {
     await context.sendSocketMessage("browser_go_forward", {});
@@ -84,6 +96,10 @@ export const wait: Tool = {
     name: WaitTool.shape.name.value,
     description: WaitTool.shape.description.value,
     inputSchema: zodToJsonSchema(WaitTool.shape.arguments),
+    annotations: {
+      title: "Wait",
+      readOnlyHint: true,
+    },
   },
   handle: async (context, params) => {
     const { time } = WaitTool.shape.arguments.parse(params);
@@ -104,6 +120,10 @@ export const pressKey: Tool = {
     name: PressKeyTool.shape.name.value,
     description: PressKeyTool.shape.description.value,
     inputSchema: zodToJsonSchema(PressKeyTool.shape.arguments),
+    annotations: {
+      title: "Press Key",
+      destructiveHint: true,
+    },
   },
   handle: async (context, params) => {
     const { key } = PressKeyTool.shape.arguments.parse(params);

src/tools/custom.ts

@@ -9,6 +9,10 @@ export const getConsoleLogs: Tool = {
     name: GetConsoleLogsTool.shape.name.value,
     description: GetConsoleLogsTool.shape.description.value,
     inputSchema: zodToJsonSchema(GetConsoleLogsTool.shape.arguments),
+    annotations: {
+      title: "Get Console Logs",
+      readOnlyHint: true,
+    },
   },
   handle: async (context, _params) => {
     const consoleLogs = await context.sendSocketMessage(
@@ -29,6 +33,10 @@ export const screenshot: Tool = {
     name: ScreenshotTool.shape.name.value,
     description: ScreenshotTool.shape.description.value,
     inputSchema: zodToJsonSchema(ScreenshotTool.shape.arguments),
+    annotations: {
+      title: "Screenshot",
+      readOnlyHint: true,
+    },
   },
   handle: async (context, _params) => {
     const screenshot = await context.sendSocketMessage(

src/tools/snapshot.ts

@@ -19,6 +19,10 @@ export const snapshot: Tool = {
     name: SnapshotTool.shape.name.value,
     description: SnapshotTool.shape.description.value,
     inputSchema: zodToJsonSchema(SnapshotTool.shape.arguments),
+    annotations: {
+      title: "Snapshot",
+      readOnlyHint: true,
+    },
   },
   handle: async (context: Context) => {
     return await captureAriaSnapshot(context);
@@ -30,6 +34,10 @@ export const click: Tool = {
     name: ClickTool.shape.name.value,
     description: ClickTool.shape.description.value,
     inputSchema: zodToJsonSchema(ClickTool.shape.arguments),
+    annotations: {
+      title: "Click",
+      destructiveHint: true,
+    },
   },
   handle: async (context: Context, params) => {
     const validatedParams = ClickTool.shape.arguments.parse(params);
@@ -52,6 +60,10 @@ export const drag: Tool = {
     name: DragTool.shape.name.value,
     description: DragTool.shape.description.value,
     inputSchema: zodToJsonSchema(DragTool.shape.arguments),
+    annotations: {
+      title: "Drag",
+      destructiveHint: true,
+    },
   },
   handle: async (context: Context, params) => {
     const validatedParams = DragTool.shape.arguments.parse(params);
@@ -74,6 +86,10 @@ export const hover: Tool = {
     name: HoverTool.shape.name.value,
     description: HoverTool.shape.description.value,
     inputSchema: zodToJsonSchema(HoverTool.shape.arguments),
+    annotations: {
+      title: "Hover",
+      destructiveHint: true,
+    },
   },
   handle: async (context: Context, params) => {
     const validatedParams = HoverTool.shape.arguments.parse(params);
@@ -96,6 +112,10 @@ export const type: Tool = {
     name: TypeTool.shape.name.value,
     description: TypeTool.shape.description.value,
     inputSchema: zodToJsonSchema(TypeTool.shape.arguments),
+    annotations: {
+      title: "Type",
+      destructiveHint: true,
+    },
   },
   handle: async (context: Context, params) => {
     const validatedParams = TypeTool.shape.arguments.parse(params);
@@ -118,6 +138,10 @@ export const selectOption: Tool = {
     name: SelectOptionTool.shape.name.value,
     description: SelectOptionTool.shape.description.value,
     inputSchema: zodToJsonSchema(SelectOptionTool.shape.arguments),
+    annotations: {
+      title: "Select Option",
+      destructiveHint: true,
+    },
   },
   handle: async (context: Context, params) => {
     const validatedParams = SelectOptionTool.shape.arguments.parse(params);

src/tools/tool.ts

@@ -1,6 +1,7 @@
 import type {
   ImageContent,
   TextContent,
+  ToolAnnotations,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { JsonSchema7Type } from "zod-to-json-schema";
 
@@ -10,6 +11,7 @@ export type ToolSchema = {
   name: string;
   description: string;
   inputSchema: JsonSchema7Type;
+  annotations?: ToolAnnotations;
 };
 
 export type ToolResult = {