browser-automation

name	browser-automation
description	CDP-powered browser automation with UID-based targeting and background operations. Use when users ask to navigate websites, fill forms, take screenshots, extract web data, test web apps, or automate browser workflows. Supports file uploads, history navigation, and reliable element interaction. Trigger phrases include "go to [url]", "click on", "fill out the form", "take a screenshot", "scrape", "automate", "test the website", "log into", or any browser interaction request.
metadata	{"version":"2.1.4"}

Browser Automation Skill

Complete browser automation workflow based on MCP Browser Server, providing stable and reliable web page operations.

Core Capabilities

• CDP-Powered Automation: Chrome DevTools Protocol for reliable, background operations
• Smart Navigation System: Auto-detect open tabs, avoid redundant navigation
• Advanced Element Interaction: UID-based targeting, accessibility tree analysis
• Content Extraction: HTML/text extraction, saved locally
• Network Requests: Send HTTP requests with browser cookies
• Advanced Features: File upload, script injection, history navigation

📖 Quick Start

🎯 Execution Flow

Standard Workflow (CDP-Powered, Recommended)

1. get_windows_and_tabs                        (Check browser state)
2. chrome_navigate(url)                        (Navigate to target page, background mode)
3. chrome_screenshot(tabId)                    (Verify loading)
4. [Optional] chrome_page_protection_enable    (Protect from user interference)
5. [Optional] chrome_accessibility_snapshot    (Get interactive elements with UIDs)
6. [Optional] chrome_click_element(uid)        (Click using UID - most reliable)
7. chrome_get_web_content(tabId)               (Extract content)
8. [Optional] chrome_page_protection_disable   (Restore user control)
9. chrome_close_tabs                           (Clean up: close opened tabs after completion)

⚠️ User Intervention: When encountering login/CAPTCHA/complex decisions, use mcp__user_interaction_tools__ask_user_confirmation:

Example parameters:

{
    "type": "user_takeover",
    "message": "Detected login required. Please complete login and click confirm.",
    "confirm_text": "Continue",
    "cancel_text": "Cancel",
    "tabId": "1625463389",
    "timeout": 300
}

CDP Advantages:

• Background execution: No tab activation, faster performance
• UID-based targeting: Most reliable element location method
• Better error handling: CDP provides detailed error information
• Persistent state: Maintains page state across operations

---

🛠️ MCP Tools Reference

Navigation & State

chrome_navigate ⭐ (Recommended)

Navigate using CDP - supports background navigation without tab activation

Parameters:

• url (string, required): Target URL
• tabId (number, required): Target tab ID
• active (boolean, default: false): Whether to activate tab (false = background)
• waitForLoad (boolean, default: true): Wait for page load event
• timeout (number, default: 30000): Navigation timeout in milliseconds

CDP Advantages:

• ✅ Background navigation (faster, no UI disruption)
• ✅ Precise load event detection
• ✅ Reuse existing tabs efficiently
• ✅ Better error reporting

Use Cases:

• Batch URL processing without switching tabs
• Automated workflows requiring stealth navigation
• Parallel page loading

---

get_windows_and_tabs

Get all browser windows and tabs

Parameters: None

Returns: All windows and tabs info (id, url, title, active)

Use Cases:

• Check if target page already open before navigation
• Avoid redundant navigation, save time
• Determine current active tab

---

chrome_close_tabs

Close one or more tabs

Parameters:

• tabIds (array, optional): Tab ID list
• url (string, optional): Match URL to close

---

Element Analysis

chrome_accessibility_snapshot ⭐ (PRIMARY - Use this first)

Capture clickable elements using CDP DOMSnapshot - returns flat list with UIDs

Parameters:

• tabId (number, required): Target tab ID

Returns:

• Flat list of interactive elements sorted by paint order and position
• Each element includes:
  • uid: Unique identifier (use with chrome_click_element)
  • selector: CSS selector
  • coordinates: {x, y} position
  • styles: Element styles
  • attributes: HTML attributes

CDP Advantages:

• ✅ PRIMARY TOOL - Always use this first for element analysis
• ✅ UID-based element targeting (most reliable)
• ✅ Complete accessibility tree analysis
• ✅ Paint order information for accurate positioning
• ✅ No visual highlighting needed

Use Cases:

• Find elements to interact with
• Analyze page structure
• Generate reliable selectors

---

Content Extraction

chrome_get_web_content

Get HTML or Markdown content from web pages using CDP. Supports background execution (no tab activation)

Parameters:

• tabId (number, required): Target tab ID to fetch content from
• outputFormat (string, optional): Output format: "html" (default), "markdown"
• selector (string, optional): CSS selector to get HTML from a specific element. If not provided, gets entire page HTML (document.documentElement.outerHTML).

CDP Advantages:

• ✅ Background execution without tab activation
• ✅ Returns extracted content directly
• ✅ Element-specific content extraction via CSS selector

Returns:

• Extracted HTML or Markdown content

Note: This tool fetches content from an existing tab. Use chrome_navigate first if you need to navigate to a URL.

---

chrome_get_interactive_elements

Get page interactive elements (legacy method)

Parameters:

• tabId (number, required): Target tab
• selector (string, optional): CSS filter
• textQuery (string, optional): Text search
• includeCoordinates (boolean, default: true): Include coordinates

⚠️ Deprecated: Use chrome_accessibility_snapshot instead for better reliability

---

Screenshots

chrome_screenshot ⭐ (Recommended)

Capture screenshots using CDP - supports background execution

Parameters:

• tabId (number, required): Target tab ID
• fullPage (boolean, default: false): Capture full page
• selector (string, optional): Capture specific element only

CDP Advantages:

• ✅ Background capture without activating tab
• ✅ Element-specific screenshots
• ✅ Full page capture support

Use Cases:

• ✅ Verify page loading after navigation
• ✅ Detect CAPTCHA or popups
• ✅ Capture specific page sections
• ✅ Batch screenshot collection

---

chrome_screenshot_with_highlights

Highlight interactive elements and capture screenshot with numbered labels (non-CDP legacy method)

Parameters:

• tabId (number, required): Target tab ID
• selector (string, optional): CSS selector to filter elements
• name (string, optional): Filename prefix (default: "highlights")
• highlightDelay (number, optional): Wait time after highlighting (default: 500ms)

Returns:

• Two file URLs:
  1. JSON file with element details and index numbers
  2. Screenshot image with numbered labels

⚠️ Deprecated (Non-CDP): This tool is not CDP-powered and may require tab activation. For better reliability and performance, use chrome_accessibility_snapshot (CDP-powered) combined with chrome_screenshot instead.

Recommended Alternative:

1. Use chrome_accessibility_snapshot to get element UIDs and metadata
2. Use chrome_screenshot for visual verification if needed

---

Page Interaction

chrome_click_element ⭐ (Recommended)

Click elements using UID (most reliable), CSS selector, or coordinates

Parameters:

• uid (string, optional): Unique ID from accessibility snapshot (MOST RELIABLE)
• selector (string, optional): CSS selector
• coordinates (object, optional): {x, y} coordinates
• tabId (number, required): Target tab ID
• button (string, default: "left"): Mouse button (left/right/middle)
• clickCount (number, default: 1): Number of clicks (1=single, 2=double)
• waitForNavigation (boolean, default: false): Wait for navigation after click
• timeout (number, default: 5000): Timeout in milliseconds

CDP Advantages:

• ✅ UID targeting - Most reliable method (get UIDs from chrome_accessibility_snapshot)
• ✅ Auto-scroll to element before clicking
• ✅ Support for right-click and double-click
• ✅ Better error messages

Recommended Workflow:

1. Use chrome_accessibility_snapshot to get element UIDs
2. Click using uid parameter for maximum reliability

---

chrome_fill_or_select ⭐ (Recommended)

Fill form elements using UID (most reliable) or CSS selector - supports automatic clearing and event triggering

Parameters:

• uid (string, optional): Unique ID from accessibility snapshot (MOST RELIABLE)
• selector (string, optional): CSS selector of the form element (alternative to uid)
• value (string, required): Value to fill
• tabId (number, required): Target tab ID
• clearFirst (boolean, default: true): Clear existing content before filling

CDP Advantages:

• ✅ UID targeting - Most reliable method (get UIDs from chrome_accessibility_snapshot)
• ✅ Automatic clearing of existing content
• ✅ Triggers proper input events (input, change, blur)
• ✅ Reliable handling of React/Vue controlled components

Recommended Workflow:

1. Use chrome_accessibility_snapshot to get element UIDs
2. Fill using uid parameter for maximum reliability

Note: Must provide either uid or selector

---

chrome_scroll ⭐ (Recommended)

Scroll page or element using CDP mouseWheel events

Parameters:

• selector (string, optional): CSS selector to scroll
• coordinates (object, optional): {x, y} where scroll is triggered
• direction (string, default: "down"): Scroll direction (up/down/left/right)
• distance (number, default: 300): Scroll distance in pixels
• tabId (number, required): Target tab ID
• timeout (number, default: 3000): Timeout in milliseconds

CDP Advantages:

• ✅ Precise pixel-based scrolling
• ✅ Directional control (up/down/left/right)
• ✅ Can target specific elements or coordinates

Best Practices:

• Provide coordinates for predictable scrolling behavior
• Use selector to scroll within specific containers

---

chrome_scroll_into_view 🆕 (Recommended)

Scroll element into view using UID (most reliable) or CSS selector - supports alignment control

Parameters:

• uid (string, optional): Unique ID from accessibility snapshot (MOST RELIABLE)
• selector (string, optional): CSS selector of the element (alternative to uid)
• block (string, default: "center"): Vertical alignment (start/center/end/nearest)
• inline (string, default: "center"): Horizontal alignment (start/center/end/nearest)
• behavior (string, default: "auto"): Scroll behavior (auto/smooth)
• tabId (number, required): Target tab ID
• timeout (number, default: 3000): Timeout in milliseconds

CDP Advantages:

• ✅ UID targeting - Most reliable method (get UIDs from chrome_accessibility_snapshot)
• ✅ Precise alignment control (center/start/end)
• ✅ Ensures element visibility before interaction
• ✅ Works with dynamically loaded content

Recommended Workflow:

1. Use chrome_accessibility_snapshot to get element UIDs
2. Scroll using uid parameter for maximum reliability

Use Cases:

• Scroll to specific element before clicking
• Ensure form fields are visible before filling
• Navigate to page sections

Note: Must provide either uid or selector

---

chrome_keyboard ⭐ (Recommended)

Simulate keyboard input using CDP - supports special keys and combinations

Parameters:

• keys (string, required): Keys to simulate (e.g., "Enter", "Ctrl+C", "A, B, C")
• selector (string, optional): Target element to focus before sending keys
• delay (number, default: 50): Delay between key sequences in milliseconds
• tabId (number, required): Target tab ID

CDP Advantages:

• ✅ Full special key support (Enter, Tab, Arrow keys, etc.)
• ✅ Modifier combinations (Ctrl+C, Shift+A, etc.)
• ✅ Sequence support with customizable delays

Examples:

• keys: "Enter" - Press Enter
• keys: "Ctrl+C" - Copy
• keys: "A, B, C" - Type A, B, C in sequence with delays

---

chrome_wait_for_element ⭐ (Recommended)

Wait for element to appear using CDP - supports background polling

Parameters:

• selector (string, required): CSS selector
• tabId (number, required): Target tab ID
• timeout (number, default: 10000): Timeout in milliseconds
• visible (boolean, default: true): Element must be visible
• pollInterval (number, default: 100): Polling interval in milliseconds
• useBinding (boolean, default: false): Use event-driven detection

CDP Advantages:

• ✅ Background polling without tab activation
• ✅ Configurable poll intervals
• ✅ Event-driven detection option (faster)

---

chrome_input_upload_file 🆕

Upload files to file input elements or drag-and-drop zones using UID or CSS selector

Parameters:

• sourceType (string, default: "base64"): Source type (url/base64)
• url (string, optional): URL of file (required if sourceType="url")
• base64Data (string, optional): Base64 file data (required if sourceType="base64")
• filename (string, optional): Filename (inferred if not provided)
• mimeType (string, optional): MIME type (inferred if not provided)
• uid (string, optional): Unique ID from accessibility snapshot (alternative to inputSelector)
• inputSelector (string, default: "input[type="file"]"): File input selector (alternative to uid)
• dropZoneSelector (string, optional): Drag-and-drop zone selector
• multiple (boolean, default: false): Upload multiple files
• files (array, optional): Array of files for multiple upload
• waitForComplete (boolean, default: false): Wait for upload completion
• successSelectors (array, optional): Selectors to detect successful upload
• errorSelectors (array, optional): Selectors to detect upload errors
• showVisual (boolean, default: true): Show visual feedback of mouse movements and clicks
• timeout (number, default: 30000): Timeout in milliseconds
• tabId (number, required): Target tab ID

CDP Advantages:

• ✅ UID targeting - Most reliable method (get UIDs from chrome_accessibility_snapshot)
• ✅ Support for URL and base64 sources
• ✅ Multiple file upload
• ✅ Drag-and-drop zone support
• ✅ Upload completion monitoring
• ✅ Visual feedback for debugging

Recommended Workflow:

1. Use chrome_accessibility_snapshot to locate file input elements
2. Upload using uid parameter for maximum reliability

Use Cases:

• Upload images/documents from URLs
• Upload base64-encoded files
• Fill file upload forms
• Drag-and-drop file uploads

---

chrome_page_protection_enable 🔒 (Recommended)

Enable page protection to prevent accidental user interactions during automation

Parameters:

• tabId (number, optional, defaults to active tab): Target tab ID

CDP Advantages:

• ✅ Creates transparent overlay to block all user interactions
• ✅ Automatically enables close warning to prevent accidental tab closure
• ✅ Protects automation workflows from manual interference
• ✅ Visual indicator shows page is under automation control

Use Cases:

• Prevent user clicks during long automation workflows
• Protect form filling operations from interruption
• Ensure data extraction completes without interference
• Multi-step workflows requiring consistent state

Best Practice: Always enable protection at the start of critical automation sequences

---

chrome_page_protection_disable 🔓 (Recommended)

Disable page protection to restore normal user interactions

Parameters:

• tabId (number, optional, defaults to active tab): Target tab ID

CDP Advantages:

• ✅ Removes overlay and restores user control
• ✅ Automatically disables close warning
• ✅ Clean cleanup after automation completes

Use Cases:

• Restore user control after automation completes
• Allow manual intervention when needed
• Clean up after failed automation workflows

IMPORTANT:

• If page protection is enabled, you MUST disable it first using this tool before attempting clicks, otherwise clicks will be blocked and have no effect
• Always call this tool when automation completes or encounters errors

---

chrome_page_protection_status

Check current page protection status for a tab

Parameters:

• tabId (number, optional, defaults to active tab): Target tab ID

Returns:

• enabled (boolean): Whether page protection is currently active
• tabId (number): The tab ID that was checked

Use Cases:

• Verify protection state before critical operations
• Debug interaction issues (blocked clicks/inputs)
• Conditional logic based on protection status

---

Network Requests

Tool Selection Guide:

Tool	Active Tab Required	Cookie Support	Large Response	Best For
fetch_api	❌ No	Specify domain	Supported	API calls with large responses
fetch_api_batch	❌ No	Specify domain	Batch supported	Multiple related requests

Decision Flow:

• Expect large response (>100KB)? → fetch_api
• Multiple requests? → fetch_api_batch

---

fetch_api

Extended background request with large response handling

Parameters:

• url (string, required): Request URL
• method (string, default: "GET"): HTTP method
• headers (object, optional): Request headers
• body (string, optional): Request body
• cookieDomain (string, optional): Cookie domain
• includeCookies (boolean, default: true): Include cookies
• uploadThreshold (number, default: 102400): Threshold for large response handling (bytes)

Feature: Handles large responses (>100KB) efficiently to avoid context overflow

---

fetch_api_batch

Send multiple HTTP requests in batch

Parameters:

• requests (array, required): Request array [{url, method, headers, body}, ...]
• cookieDomain (string, optional): Cookie domain for all requests
• delayMs (number, default: 100): Delay between requests (ms)
• uploadBatchResult (boolean, default: true): Handle batch results for large responses

---

Advanced Features

chrome_execute_script ⭐ (Recommended)

Execute one-time JavaScript and synchronously retrieve results

Parameters:

• jsScript (string, required): JavaScript function body as a string
• args (array, optional, default: []): Arguments to pass to the function
• tabId (number, required): Target tab ID
• timeout (number, default: 5000): Timeout in milliseconds for script execution
• world (string, default: "ISOLATED"): Execution context (ISOLATED/MAIN)

Execution Contexts:

• ISOLATED (default): Safer, extension context, isolated from page
• MAIN: Page context, can access page variables and functions

CDP Advantages:

• ✅ Synchronous result retrieval (unlike chrome_inject_script)
• ✅ One-time execution (no persistent code injection)
• ✅ Function argument support with serialization
• ✅ Timeout control for safety

Use Cases:

• Extract data from page (e.g., () => document.title)
• Perform calculations with page data
• Query DOM state and return values
• Execute utilities without persistent injection

Examples:

// Get page title
jsScript: "() => document.title"

// Calculate with arguments
jsScript: "(a, b) => a + b"
args: [5, 3]

// Extract JSON data from page
jsScript: "() => JSON.parse(document.getElementById('data').textContent)"

Key Difference from chrome_inject_script:

• chrome_execute_script: One-time execution, returns value synchronously
• chrome_inject_script: Persistent code injection, no return value

---

chrome_inject_script

Inject persistent JavaScript into page

Parameters:

• jsScript (string, required): JavaScript code
• type (string, required): Execution environment ("ISOLATED" or "MAIN")
• url (string, optional): Inject into specific URL page

Execution Environments:

• ISOLATED: Isolated environment (recommended, secure)
• MAIN: Main page environment (can access page globals)

---

chrome_send_command_to_inject_script

Send event to injected script

Parameters:

• eventName (string, required): Event name
• payload (string, optional): JSON format payload
• tabId (number, required): Target tab

---

chrome_console

Capture console output

Parameters:

• url (string, optional): Target page URL
• maxMessages (number, default: 100): Maximum messages
• includeExceptions (boolean, default: true): Include exceptions

---

⚡ Best Practices

1. Prefer CDP Tools

Why CDP Tools are Better:

• ✅ Background execution (no tab switching, faster)
• ✅ More reliable (Chrome DevTools Protocol)
• ✅ Better error reporting
• ✅ UID-based element targeting (most accurate)

Recommended Tool Mapping:

Task	Recommended Tool	Notes
Navigate	chrome_navigate	Background mode, faster
Screenshot	chrome_screenshot	Element-specific, full page support
Click	chrome_click_element	UID-based targeting
Fill form	chrome_fill_or_select	Auto-triggers events
Scroll	chrome_scroll	Precise pixel control
Keyboard	chrome_keyboard	Special keys support
Wait	chrome_wait_for_element	Background polling
Analyze page	chrome_accessibility_snapshot	UID-based element analysis

---

2. Smart Navigation

Standard Flow (CDP-Powered):

1. get_windows_and_tabs             (Check existing tabs)
2. Analyze if matching tab exists
3. Match → Reuse tabId | No match → chrome_navigate

URL Matching Rules:

• Protocol agnostic: http:// == https://
• www optional: www.jd.com == jd.com
• Query param order irrelevant: ?a=1&b=2 == ?b=2&a=1
• Trailing slash ignored: /products/ == /products
• Hash removed: #section removed before matching

Performance Gain: Background navigation saves 3-5 seconds per page

---

3. Element Interaction Workflow

✅ Correct Approach (UID-based, Most Reliable):

1. chrome_accessibility_snapshot  (Get elements with UIDs)
2. chrome_click_element(uid="...")  (Click using UID)

❌ Old Approach (Selector-based, Less Reliable):

1. chrome_screenshot_with_highlights  (Slower, visual only)
2. chrome_click_element(selector="...")  (May fail if selector changes)

Why UID is Better:

• Immune to CSS class changes
• Works with dynamically generated selectors
• No ambiguity with multiple matching elements

---

4. Navigation Verification (Performance Optimized)

✅ Correct Approach (3 tools, ~2-3 seconds):

1. get_windows_and_tabs              (0.5s)
2. chrome_navigate                   (1-2s, background)
3. chrome_screenshot                 (0.5s)

❌ Wrong Approach (6+ tools, 60+ seconds):

1. get_windows_and_tabs
2. chrome_accessibility_snapshot      ← Over-verification (use only when interaction needed)
3. fetch_file (screenshot)            ← Unnecessary
4. fetch_file (JSON)                  ← Unnecessary
5. Read JSON                          ← Why?
6. get_windows_and_tabs again         ← Duplicate

---

5. Parameter Best Practices

chrome_get_web_content:

• ✅ Must provide tabId (required parameter)
• ✅ Use selector to extract specific element content
• ✅ Prefer outputFormat="markdown" for better performance (smaller size, faster processing, clearer structure)

chrome_screenshot:

• ✅ Use fullPage: true only when necessary (performance impact)
• ✅ Use selector to capture specific elements

chrome_click_element:

• ✅ Prefer UID over selector for reliability
• Get UIDs from chrome_accessibility_snapshot first
• Only use selector/coordinates as fallback

chrome_fill_or_select:

• ✅ Prefer UID over selector for reliability
• Get UIDs from chrome_accessibility_snapshot first
• clearFirst: true by default (auto-clears existing content)

chrome_scroll_into_view:

• ✅ Prefer UID over selector for reliability
• Get UIDs from chrome_accessibility_snapshot first
• Use block and inline for precise alignment control

chrome_scroll:

• ✅ Provide coordinates parameter for predictable scrolling
• Recommended: {x: 640, y: 360} (viewport center for 1280x720)

---

6. Page Protection Best Practices

When to Enable Protection:

• ✅ Long automation workflows (>10 seconds)
• ✅ Multi-step form filling
• ✅ Critical data extraction operations
• ✅ Workflows where user interference could cause errors

When to Disable Protection:

• ✅ After automation completes successfully
• ✅ When encountering errors (cleanup)
• ✅ Before manual user intervention is needed
• ✅ Before closing tabs

Protection Workflow Pattern:

try {
    chrome_page_protection_enable(tabId)      // Enable at start
    // ... automation steps ...
} finally {
    chrome_page_protection_disable(tabId)     // Always cleanup
}

⚠️ Critical Rules:

• MUST disable protection before clicks if already enabled
• ALWAYS disable protection when automation ends
• Check status with chrome_page_protection_status if clicks fail unexpectedly
• Don't forget to disable on error paths

---

7. Error Handling

Error Type	Strategy	Example
Navigation timeout	Increase timeout, check network	chrome_navigate(url, timeout=60000)
Element not found	Use chrome_wait_for_element first	Wait before clicking
Screenshot timeout	Reduce viewport size or skip fullPage	Use default 800x600
Hook denies tool execution	Check parameter constraints	Verify required parameters
Network request timeout	Retry with exponential backoff	Wait 2s, 4s, 8s between retries

General Principles:

• Use chrome_wait_for_element before interacting with dynamic content
• Check hook constraints before tool calls (see Section 4)
• For unreliable pages: Take screenshot to verify state before proceeding

---

🎯 Quick Tool Selection Guide

"I need to..."

Task	Recommended Tool (CDP)	Notes
Open a webpage	chrome_navigate ⭐	Background mode, faster
Check if page loaded	chrome_screenshot ⭐	Visual verification
Find interactive elements	chrome_accessibility_snapshot ⭐	Returns UIDs (PRIMARY)
Click a button	chrome_click_element(uid) ⭐	Use UID from snapshot
Fill a form	chrome_fill_or_select ⭐	Auto-triggers events
Scroll down/up	chrome_scroll ⭐	Precise pixel control
Scroll to element	chrome_scroll_into_view 🆕	Alignment control
Upload a file	chrome_input_upload_file 🆕	Supports URL/base64
Type keys	chrome_keyboard ⭐	Special keys support
Wait for element	chrome_wait_for_element ⭐	Background polling
Extract page content	chrome_get_web_content	HTML or Markdown
Execute JavaScript	chrome_execute_script ⭐	Returns value synchronously
Send API request	See Network Requests table	Choose based on cookies/size
Go back/forward	chrome_go_back_or_forward 🆕	History navigation
Check for errors	chrome_screenshot ⭐	Visual inspection
Protect page from interference	chrome_page_protection_enable 🔒	Blocks user interactions
Restore user control	chrome_page_protection_disable 🔓	Removes protection overlay
Check protection status	chrome_page_protection_status	Debug interaction issues

Legend: ⭐ = CDP-powered (recommended), 🆕 = New feature

Decision Tree (CDP-Optimized)

Task: Navigate to a page
  ├─ Check browser state first? → get_windows_and_tabs
  ├─ Navigate (background) → chrome_navigate ⭐
  └─ Verify loading → chrome_screenshot ⭐

Task: Interact with elements (UID-based workflow)
  ├─ Get interactive elements → chrome_accessibility_snapshot ⭐
  ├─ Click button → chrome_click_element(uid="...") ⭐
  ├─ Fill form → chrome_fill_or_select(selector, value) ⭐
  └─ Extract data → chrome_get_web_content

Task: Advanced interaction
  ├─ Upload file → chrome_input_upload_file 🆕
  ├─ Type special keys → chrome_keyboard ⭐
  ├─ Scroll to element → chrome_scroll_into_view 🆕
  └─ Go back/forward → chrome_go_back_or_forward 🆕

Task: Execute custom logic
  ├─ Need return value? → chrome_execute_script ⭐ (one-time, returns value)
  └─ Need persistent code? → chrome_inject_script (persistent injection)

Task: Send network requests
  ├─ Large response (>100KB)? → fetch_api
  └─ Multiple requests? → fetch_api_batch

Task: Page protection (prevent interference)
  ├─ Start automation → chrome_page_protection_enable 🔒
  ├─ Check status → chrome_page_protection_status
  ├─ Clicks not working? → chrome_page_protection_disable 🔓 (must disable first)
  └─ End automation → chrome_page_protection_disable 🔓

---

🚫 Common Mistakes

❌ Wrong Approach	✅ Correct Approach
Navigate blindly without checking browser state	Call get_windows_and_tabs first
Use selector-based clicking directly	Use chrome_accessibility_snapshot first to get UIDs
Use basic screenshot for element analysis	Use chrome_accessibility_snapshot ⭐ (PRIMARY tool)
Click with selector only	Use chrome_click_element(uid) ⭐ (more reliable)
Fill form with selector only	Use chrome_fill_or_select(uid) ⭐ (more reliable)
Use chrome_get_interactive_elements	Use chrome_accessibility_snapshot ⭐
Use fullPage=true without reason	Avoid (performance issue)
Call 7-8 tools for simple verification	3-4 tools are enough
Don't provide coordinates for scrolling	Provide coordinates for predictable behavior
Expect HTML in response	Returns URL, use WebFetch to get HTML content
Try to navigate with chrome_get_web_content	Use chrome_navigate first, then fetch content
Clicks not working, protection enabled	Call chrome_page_protection_disable 🔓 first
Forget to disable protection after automation	Always call chrome_page_protection_disable 🔓 at the end

---

📌 Understanding Tool Selection

Scenario A: Verify Page Loading (Post-Navigation Check)

• Goal: Confirm the page has loaded successfully
• Tool: chrome_screenshot ⭐ (lightweight, 0.5-1 second)
• When: Immediately after chrome_navigate
• Example: Check if homepage rendered correctly

Scenario B: Find Elements for Interaction

• Goal: Locate elements and get UIDs for clicking/filling
• Tool: chrome_accessibility_snapshot ⭐ (PRIMARY - returns elements with UIDs)
• When: Before clicking, filling, or analyzing page structure
• Example: Find the search button UID before clicking

Decision Rule:

Need to interact with elements? → chrome_accessibility_snapshot ⭐
Just checking if page loaded?   → chrome_screenshot ⭐

---

Version History

• v2.1.4 (2025-12-27): Parameter requirement update
  • 🔄 Changed: All tabId parameters from optional to required
  • 📖 Rationale: Explicit tab targeting improves reliability and reduces ambiguity in multi-tab scenarios

---

Maintainer: datasaver-agent project team

Use Cases: Data extraction, automated testing, page interaction automation