feat: Add tool annotations for improved LLM tool understanding

[bryankthompson]

Summary

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

Changes

API Tools (7 tools)

• search_engine - readOnlyHint: true, openWorldHint: true
• scrape_as_markdown - readOnlyHint: true, openWorldHint: true
• search_engine_batch - readOnlyHint: true, openWorldHint: true
• scrape_batch - readOnlyHint: true, openWorldHint: true
• scrape_as_html - readOnlyHint: true, openWorldHint: true
• extract - readOnlyHint: true, openWorldHint: true
• session_stats - readOnlyHint: true

Web Data Tools (43 tools)

All web_data_* dataset tools receive:

• readOnlyHint: true - these tools only fetch data
• openWorldHint: true - they access external APIs
• title - dynamically generated human-readable title

Browser Tools (13 tools)

• Read-only (5): scraping_browser_snapshot, scraping_browser_screenshot, scraping_browser_get_html, scraping_browser_get_text, scraping_browser_network_requests, scraping_browser_wait_for_ref
• Destructive (7): scraping_browser_navigate, scraping_browser_go_back, scraping_browser_go_forward, scraping_browser_click_ref, scraping_browser_type_ref, scraping_browser_scroll, scraping_browser_scroll_to_ref

Why This Matters

Tool annotations provide semantic metadata that helps MCP clients:

• Auto-approve read-only operations without user confirmation
• Display appropriate warnings for destructive operations
• Enable smarter caching and retry strategies
• Provide better UI/UX with human-readable tool titles

Testing

• npm install succeeds
• Syntax validation passes (node --check)
• All 13 browser tools have annotations verified
• All 7 API tools have annotations verified
• Dataset tool generation includes annotations (43 tools)

Before/After

Before:

let scraping_browser_navigate = {
    name: 'scraping_browser_navigate',
    description: 'Navigate a scraping browser session to a new URL',
    parameters: z.object({...}),
    execute: async({url})=>{ ... }
};

After:

let scraping_browser_navigate = {
    name: 'scraping_browser_navigate',
    description: 'Navigate a scraping browser session to a new URL',
    annotations: {
        title: 'Browser Navigate',
        destructiveHint: true,
        openWorldHint: true,
    },
    parameters: z.object({...}),
    execute: async({url})=>{ ... }
};

🤖 Generated with Claude Code

[meirk-brd]

Hi @triepod-ai,

thank you for your contribution to Bright Data MCP. We’ll review your PR soon and proceed with the merge.