---

name: tools-and-actions description: "Build and debug Browser Use tools/actions: custom Tools/Controller actions, default browser/file actions, ActionResult returns, parameter injection, sensitive data, security guardrails, and validation." disable-model-invocation: true metadata: disco-role: operating license: MIT

Tools and Actions

Use this sub-skill when the user needs Browser Use actions, custom tools, file operations, upload/download handling, sensitive data placeholders, or action validation. Prefer ChatBrowserUse in examples unless the user already chose another model.

Route Here

• User asks to add @tools.action(...), Tools(), Controller, custom actions, action filters, 2FA helpers, human-in-the-loop actions, deterministic browser helpers, or direct tools.<action>() calls.
• User asks which default actions exist, how to remove actions, or why an action schema/model is rejected.
• User asks about ActionResult, extracted_content, long_term_memory, error, is_done, success, attachments/images, or completion semantics.
• User asks about available_file_paths, write_file, read_file, replace_file, upload_file, downloaded files, or file containment errors.
• User asks how sensitive_data works, how to use <secret>name</secret>, or how to keep secrets scoped to allowed domains.
• User hit tool validation, parameter injection, domain filter, file upload, or security guardrail failures.

Route Elsewhere

• Agent construction, task prompting, run loops, history inspection, callbacks, initial actions, or Python workflow structure: ../agent-programming/SKILL.md.
• Browser/Profile/CDP/session/proxy/download directory/domain navigation configuration: ../browser-control/SKILL.md.
• LLM adapters, structured output models, extraction LLMs, cost, fallback models, or provider credentials: ../llm-and-output/SKILL.md.
• Terminal browser-use / bu CLI sessions and CLI upload commands: ../cli-and-sessions/SKILL.md.
• Cloud/sandbox/MCP/skills/telemetry/production integrations: ../production-integrations/SKILL.md.

Safe Defaults

• Import Tools, ActionResult, and BrowserSession from browser_use; Controller is a backwards-compatible alias for Tools.
• Use Pydantic v2 models for complex custom action input; keep action function parameters explicit and typed.
• Name injected browser parameters exactly browser_session, page_extraction_llm, file_system, available_file_paths, page_url, cdp_client, has_sensitive_data, extraction_schema, or context.
• Do not define **kwargs on a custom action; the registry rejects it. Use explicit parameters or a Pydantic param_model.
• Return ActionResult when the agent needs reasoning context, memory, errors, completion status, files, or attachments; simple strings are accepted but less expressive.
• Scope dangerous or credentialed custom actions with allowed_domains=[...] when possible.
• Use Tools(exclude_actions=[...]) or tools.exclude_action(name) to remove defaults that do not fit the task.
• Pass user-provided upload files through Agent(..., available_file_paths=[...]); never invent local paths.
• Use sensitive_data placeholders instead of embedding passwords or API keys in tasks.

Minimal Custom Tool

from browser_use import ActionResult, Agent, BrowserSession, ChatBrowserUse, Tools

tools = Tools()

@tools.action('Ask the user for a one-line confirmation')
async def ask_user(question: str) -> ActionResult:
    answer = input(f'{question} > ')
    return ActionResult(extracted_content=f'User answered: {answer}')

agent = Agent(task='Ask for confirmation, then continue', llm=ChatBrowserUse(), tools=tools)

For browser-aware actions, use the exact injected name:

@tools.action('Read current page URL')
async def current_url(browser_session: BrowserSession) -> ActionResult:
    url = await browser_session.get_current_page_url()
    return ActionResult(extracted_content=url, long_term_memory=f'Current URL: {url}')

Custom Action Patterns

• Loose parameters: async def fill_field(index: int, text: str, browser_session: BrowserSession); Browser Use auto-generates a Pydantic model for non-special parameters.
• Pydantic model first: define a model and pass param_model=MyParams, then write async def action(params: MyParams, browser_session: BrowserSession).
• Domain-filtered action: @tools.action('Use only on billing pages', allowed_domains=['https://billing.example.com']).
• Sequence-ending action: pass terminates_sequence=True for navigation-like actions where queued multi-actions should stop after execution.
• Direct call in tests/debugging: many registered actions can be called as await tools.read_file(file_name='x.md', browser_session=session, file_system=fs, available_file_paths=[]).

See references/custom-tools.md for full patterns and validation rules.

Default Actions

Core defaults include:

• Navigation and tabs: search, navigate, go_back, wait, switch, close.
• Page interaction: click, input, upload_file, scroll, find_text, send_keys, dropdown actions.
• Page content: extract, search_page, find_elements, evaluate, screenshot, save_pdf.
• File operations: write_file, read_file, replace_file.
• Completion: done or structured done when output_model is configured.

See references/default-actions.md for action parameters, when to exclude defaults, JavaScript evaluation cautions, and file-action behavior.

File and Secret Guardrails

• write_file supports text/document outputs such as .txt, .md, .json, .jsonl, .csv, .html, .xml, .pdf, and .docx; it rejects binary/image extensions such as .png and .jpg.
• replace_file requires exact old_str; read the file first when unsure.
• read_file can read managed files and user/downloaded files from available_file_paths; large content is summarized in memory but full content is returned for the current step.
• upload_file accepts paths from available_file_paths, Browser Use downloads, remote-browser paths, or managed FileSystem files; local uploads are checked for existence and nonzero size.
• Sensitive values are provided as sensitive_data and referenced as <secret>key</secret>; domain-specific secrets are only exposed on matching URLs.
• Pair sensitive_data with Browser(..., allowed_domains=[...]) for prompt-injection resistance.

See references/security-and-files.md for guardrail details and examples.

Validate Before Shipping

Run the bundled helper after editing tool code or snippets:

python skills/disco/browser-use/sub-skills/tools-and-actions/scripts/validate_custom_tool.py

The helper checks imports, registry schema generation, injected parameter names, validation errors, domain filtering, and ActionResult normalization without launching a browser or making network calls.

Troubleshooting First Moves

• Import failure: verify package install and use uv pip install browser-use; install Chromium separately when the task needs a live browser.
• requires browser_session but none provided: use the tool through Agent(..., tools=tools) or pass browser_session in direct tests.
• conflicts with special argument: rename the parameter or use the required special type, usually BrowserSession.
• Invalid parameters: inspect the generated Pydantic schema or run validate_custom_tool.py.
• File upload unavailable: add the path to available_file_paths or write/read through the managed file system first.
• Secrets not substituted: confirm placeholder spelling, non-empty values, matching domain pattern, and allowed_domains coverage.
• CDP/browser action timeout: retry, restart the browser/session, or route session setup to ../browser-control/SKILL.md.

See references/troubleshooting.md for symptom-to-fix tables.

Hard Case Prompts This Sub-skill Should Handle

• Build an authenticated data-entry agent with domain-scoped secrets, a custom 2FA action, file upload from available_file_paths, and structured status messages; route browser profile setup to ../browser-control/SKILL.md and output schema setup to ../llm-and-output/SKILL.md.
• Debug a failing custom action that uses browser instead of browser_session, has **kwargs, tries to upload ../note.md, and leaks a password in history; produce safe corrected code and validation steps.