feat: Add tool annotations for improved LLM tool understanding

src/index.ts

@@ -189,6 +189,9 @@ export default function ({ config }: { config: z.infer<typeof configSchema> }) {
             );
           }
         },
+        {
+          annotations: tool.schema.annotations,
+        },
       );
     } else {
       console.warn(

src/tools/act.ts

@@ -31,6 +31,10 @@ const actSchema: ToolSchema<typeof ActInputSchema> = {
   name: "browserbase_stagehand_act",
   description: `Perform a single action on the page (e.g., click, type).`,
   inputSchema: ActInputSchema,
+  annotations: {
+    title: "Perform Action",
+    destructiveHint: true,
+  },
 };
 
 async function handleAct(

src/tools/agent.ts

@@ -26,6 +26,10 @@ const agentSchema: ToolSchema<typeof AgentInputSchema> = {
   name: "browserbase_stagehand_agent",
   description: `Execute a task autonomously using Gemini Computer Use agent. The agent will navigate and interact with web pages to complete the given task.`,
   inputSchema: AgentInputSchema,
+  annotations: {
+    title: "Execute Agent Task",
+    destructiveHint: true,
+  },
 };
 
 async function handleAgent(

src/tools/extract.ts

@@ -27,6 +27,10 @@ const extractSchema: ToolSchema<typeof ExtractInputSchema> = {
   name: "browserbase_stagehand_extract",
   description: `Extract structured data or text from the current page using an instruction.`,
   inputSchema: ExtractInputSchema,
+  annotations: {
+    title: "Extract Data",
+    readOnlyHint: true,
+  },
 };
 
 async function handleExtract(

src/tools/navigate.ts

@@ -11,9 +11,13 @@ type NavigateInput = z.infer<typeof NavigateInputSchema>;
 
 const navigateSchema: ToolSchema<typeof NavigateInputSchema> = {
   name: "browserbase_stagehand_navigate",
-  description: `Navigate to a URL in the browser. Only use this tool with URLs you're confident will work and be up to date. 
+  description: `Navigate to a URL in the browser. Only use this tool with URLs you're confident will work and be up to date.
     Otherwise, use https://google.com as the starting point`,
   inputSchema: NavigateInputSchema,
+  annotations: {
+    title: "Navigate to URL",
+    destructiveHint: true,
+  },
 };
 
 async function handleNavigate(

src/tools/observe.ts

@@ -30,6 +30,10 @@ const observeSchema: ToolSchema<typeof ObserveInputSchema> = {
   name: "browserbase_stagehand_observe",
   description: `Find interactive elements on the page from an instruction; optionally return an action.`,
   inputSchema: ObserveInputSchema,
+  annotations: {
+    title: "Observe Elements",
+    readOnlyHint: true,
+  },
 };
 
 async function handleObserve(

src/tools/screenshot.ts

@@ -21,6 +21,10 @@ const screenshotSchema: ToolSchema<typeof ScreenshotInputSchema> = {
   name: "browserbase_screenshot",
   description: `Capture a full-page screenshot and return it (and save as a resource).`,
   inputSchema: ScreenshotInputSchema,
+  annotations: {
+    title: "Take Screenshot",
+    readOnlyHint: true,
+  },
 };
 
 async function handleScreenshot(

src/tools/session.ts

@@ -24,6 +24,10 @@ const createSessionSchema: ToolSchema<typeof CreateSessionInputSchema> = {
   description:
     "Create or reuse a Browserbase browser session and set it as active.",
   inputSchema: CreateSessionInputSchema,
+  annotations: {
+    title: "Create Session",
+    destructiveHint: true,
+  },
 };
 
 // Handle function for CreateSession using SessionManager
@@ -139,6 +143,10 @@ const closeSessionSchema: ToolSchema<typeof CloseSessionInputSchema> = {
   description:
     "Close the current Browserbase session and reset the active context.",
   inputSchema: CloseSessionInputSchema,
+  annotations: {
+    title: "Close Session",
+    destructiveHint: true,
+  },
 };
 
 async function handleCloseSession(context: Context): Promise<ToolResult> {

src/tools/tool.ts

@@ -1,6 +1,7 @@
 import type {
   ImageContent,
   TextContent,
+  ToolAnnotations,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { z } from "zod";
 import type { Context } from "../context.js";
@@ -9,6 +10,7 @@ export type ToolSchema<Input extends InputType> = {
   name: string;
   description: string;
   inputSchema: Input;
+  annotations?: ToolAnnotations;
 };
 
 // Export InputType

src/tools/url.ts

@@ -18,6 +18,10 @@ const getUrlSchema: ToolSchema<typeof GetUrlInputSchema> = {
   name: "browserbase_stagehand_get_url",
   description: "Return the current page URL (full URL with query/fragment).",
   inputSchema: GetUrlInputSchema,
+  annotations: {
+    title: "Get Current URL",
+    readOnlyHint: true,
+  },
 };
 
 async function handleGetUrl(