feat: Add tool annotations for improved LLM tool understanding

[triepod-ai]

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint, title) to all 9 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

Changes

Type Updates

• Added ToolAnnotations import from @modelcontextprotocol/sdk/types.js
• Extended ToolSchema type to include optional annotations field
• Updated index.ts to pass annotations when registering tools with the server

Tools Annotated

Destructive tools (destructiveHint: true):

Tool	Title	Reason
browserbase_stagehand_navigate	Navigate to URL	Changes page state
browserbase_session_create	Create Session	Creates browser resources
browserbase_session_close	Close Session	Destroys browser resources
browserbase_stagehand_act	Perform Action	Performs page interactions
browserbase_stagehand_agent	Execute Agent Task	Autonomous multi-step actions

Read-only tools (readOnlyHint: true):

Tool	Title	Reason
browserbase_stagehand_extract	Extract Data	Only reads page content
browserbase_stagehand_observe	Observe Elements	Only identifies elements
browserbase_stagehand_get_url	Get Current URL	Only reads current URL
browserbase_screenshot	Take Screenshot	Captures current state without modification

Why This Matters

• Semantic metadata: Annotations provide information beyond descriptions that helps LLMs understand tool behavior
• Safer execution: LLMs can distinguish read-only from destructive operations, enabling smarter tool selection
• Better decisions: LLMs can prioritize read-only tools for information gathering before taking destructive actions
• Human-readable titles: The title annotation provides cleaner names for tool display

Testing

• Code follows MCP SDK annotation patterns
• All 9 tools have appropriate annotations
• Annotations correctly categorize read-only vs destructive behavior
• CI will verify TypeScript compilation

Before/After Example

Before:

const extractSchema = {
  name: "browserbase_stagehand_extract",
  description: "Extract structured data...",
  inputSchema: ExtractInputSchema,
};

After:

const extractSchema = {
  name: "browserbase_stagehand_extract",
  description: "Extract structured data...",
  inputSchema: ExtractInputSchema,
  annotations: {
    title: "Extract Data",
    readOnlyHint: true,
  },
};

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR adds MCP tool annotations to all 9 browser automation tools, providing semantic metadata that helps LLMs make safer and more informed tool execution decisions. The implementation correctly categorizes tools as read-only (extract, observe, get_url, screenshot) or destructive (navigate, act, agent, session_create, session_close) based on their actual behavior.

Key Changes:

• Extended ToolSchema type with optional annotations field in src/tools/tool.ts
• Updated tool registration in src/index.ts to pass annotations to Smithery server
• Added title, readOnlyHint, and destructiveHint annotations to all 9 tools
• Annotations align with tool behavior: read-only tools only observe/extract, destructive tools modify state

Benefits:

• LLMs can prioritize read-only tools for information gathering before taking actions
• Better tool selection based on operation safety
• Cleaner tool display with human-readable titles
• No runtime behavior changes, purely additive metadata

The implementation is clean, well-structured, and follows MCP SDK patterns correctly.

Confidence Score: 5/5

• This PR is safe to merge with no identified issues
• The changes are purely additive metadata that doesn't affect runtime behavior. All annotations correctly reflect tool behavior (read-only vs destructive), type definitions are properly extended, and integration follows MCP SDK patterns. No logic changes, no breaking changes, and implementation is consistent across all tools.
• No files require special attention

Important Files Changed

Filename	Overview
src/tools/tool.ts	Added ToolAnnotations import and extended ToolSchema type with optional annotations field
src/index.ts	Updated tool registration to pass annotations to Smithery server via options object
src/tools/act.ts	Added destructiveHint annotation correctly - performs page interactions that modify state
src/tools/session.ts	Added destructiveHint annotations correctly - creates/destroys browser session resources
src/tools/agent.ts	Added destructiveHint annotation correctly - executes autonomous multi-step actions

Sequence Diagram

sequenceDiagram
    participant LLM
    participant MCPServer as MCP Server
    participant Smithery as Smithery Tool Handler
    participant Tool as Tool Implementation
    participant Browser as Browserbase

    Note over LLM,Browser: Tool Registration Flow
    MCPServer->>Tool: Load tool definitions
    Tool->>Tool: Add annotations (title, readOnlyHint/destructiveHint)
    Tool-->>MCPServer: Return ToolSchema with annotations
    MCPServer->>Smithery: Register tool with annotations
    Note over Smithery: Stores metadata:<br/>- name<br/>- description<br/>- inputSchema<br/>- annotations

    Note over LLM,Browser: Tool Execution Flow (with annotation awareness)
    LLM->>LLM: Analyze available tools with annotations
    Note over LLM: Prefers readOnlyHint tools for<br/>information gathering
    LLM->>MCPServer: Call tool (e.g., browserbase_stagehand_extract)
    MCPServer->>Smithery: Route to tool handler
    Smithery->>Tool: Execute with params
    Tool->>Browser: Perform operation (read/write based on annotation)
    Browser-->>Tool: Return result
    Tool-->>Smithery: Return ToolResult
    Smithery-->>MCPServer: Return content
    MCPServer-->>LLM: Return result with awareness of operation safety

Loading

[greptile-apps]

Greptile found no issues!

From now on, if a review finishes and we haven't found any issues, we will not post anything, but you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}