From a58d982059590a41bbace711966b2493f6d91ae0 Mon Sep 17 00:00:00 2001 From: triepod-ai Date: Sun, 21 Dec 2025 15:25:32 -0600 Subject: [PATCH] feat: Add tool annotations for improved LLM tool understanding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add readOnlyHint and destructiveHint annotations to all tools to help LLMs better understand tool behavior and make safer decisions. Changes: - Added ToolAnnotations import and annotations field to ToolSchema type - Added destructiveHint: true to navigation and action tools: - browserbase_stagehand_navigate (changes page state) - browserbase_session_create (creates resources) - browserbase_session_close (destroys resources) - browserbase_stagehand_act (performs page actions) - browserbase_stagehand_agent (autonomous actions) - Added readOnlyHint: true to read-only tools: - browserbase_stagehand_extract (data extraction) - browserbase_stagehand_observe (element observation) - browserbase_stagehand_get_url (URL query) - browserbase_screenshot (captures current state) - Added title annotations for human-readable display - Updated index.ts to pass annotations when registering tools This improves tool safety metadata for MCP clients. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/index.ts | 3 +++ src/tools/act.ts | 4 ++++ src/tools/agent.ts | 4 ++++ src/tools/extract.ts | 4 ++++ src/tools/navigate.ts | 6 +++++- src/tools/observe.ts | 4 ++++ src/tools/screenshot.ts | 4 ++++ src/tools/session.ts | 8 ++++++++ src/tools/tool.ts | 2 ++ src/tools/url.ts | 4 ++++ 10 files changed, 42 insertions(+), 1 deletion(-) diff --git a/src/index.ts b/src/index.ts index f77c6a4..bf2484d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -189,6 +189,9 @@ export default function ({ config }: { config: z.infer }) { ); } }, + { + annotations: tool.schema.annotations, + }, ); } else { console.warn( diff --git a/src/tools/act.ts b/src/tools/act.ts index d395a66..a5a7843 100644 --- a/src/tools/act.ts +++ b/src/tools/act.ts @@ -31,6 +31,10 @@ const actSchema: ToolSchema = { 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( diff --git a/src/tools/agent.ts b/src/tools/agent.ts index e333079..26baf5c 100644 --- a/src/tools/agent.ts +++ b/src/tools/agent.ts @@ -26,6 +26,10 @@ const agentSchema: ToolSchema = { 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( diff --git a/src/tools/extract.ts b/src/tools/extract.ts index 7bfb56b..3fc59fe 100644 --- a/src/tools/extract.ts +++ b/src/tools/extract.ts @@ -27,6 +27,10 @@ const extractSchema: ToolSchema = { 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( diff --git a/src/tools/navigate.ts b/src/tools/navigate.ts index c6309a0..62860e5 100644 --- a/src/tools/navigate.ts +++ b/src/tools/navigate.ts @@ -11,9 +11,13 @@ type NavigateInput = z.infer; const navigateSchema: ToolSchema = { 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( diff --git a/src/tools/observe.ts b/src/tools/observe.ts index b473300..525de01 100644 --- a/src/tools/observe.ts +++ b/src/tools/observe.ts @@ -30,6 +30,10 @@ const observeSchema: ToolSchema = { 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( diff --git a/src/tools/screenshot.ts b/src/tools/screenshot.ts index facc895..575ee79 100644 --- a/src/tools/screenshot.ts +++ b/src/tools/screenshot.ts @@ -21,6 +21,10 @@ const screenshotSchema: ToolSchema = { 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( diff --git a/src/tools/session.ts b/src/tools/session.ts index aa2406a..a9ef6b9 100644 --- a/src/tools/session.ts +++ b/src/tools/session.ts @@ -24,6 +24,10 @@ const createSessionSchema: ToolSchema = { 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 = { 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 { diff --git a/src/tools/tool.ts b/src/tools/tool.ts index e7622d5..2c1ae58 100644 --- a/src/tools/tool.ts +++ b/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 = { name: string; description: string; inputSchema: Input; + annotations?: ToolAnnotations; }; // Export InputType diff --git a/src/tools/url.ts b/src/tools/url.ts index da7e124..a67a7a1 100644 --- a/src/tools/url.ts +++ b/src/tools/url.ts @@ -18,6 +18,10 @@ const getUrlSchema: ToolSchema = { 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(