[Feature] exclude tools from agent

[tkattkat]

why

Allow users to exclude specific tools from agent

what changed

• Added excludeTools option to agent.execute() that accepts an array of tool names to exclude
• Excluded tools are filtered from both the toolset and system prompt
• Feature is experimental and not supported in CUA mode

test plan

const stagehand = new Stagehand({
  env: "LOCAL",
  experimental: true,
});
await stagehand.init();

const agent = stagehand.agent();
const result = await agent.execute({
  instruction: "click the submit button",
  excludeTools: ["screenshot", "extract"],
});

---

Summary by cubic

Adds an excludeTools option to agent.execute so you can disable specific tools per run. Excluded tools are removed from both the available toolset and the system prompt to reduce unwanted calls.

• New Features
  • agent.execute({ excludeTools: string[] }) to skip tools; experimental and not supported in CUA mode
  • createAgentTools now applies mode-based and explicit exclusions
  • System prompt builds the tools list dynamically and omits excluded tools
  • Validation enforces no excludeTools in CUA and requires experimental; handler passes the option to tools and prompt

^{Written for commit dac5f80. Summary will update automatically on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: dac5f80

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 6 files

[greptile-apps]

Greptile Summary

This PR adds support for excluding specific tools from agent execution via the excludeTools option. The implementation filters tools from both the actual toolset and the system prompt to prevent the agent from using excluded tools.

Key changes:

• Refactored system prompt generation to extract tool definitions into a buildToolsSection function that supports filtering by tool name
• Updated filterTools function to apply both mode-based filtering (dom/hybrid) and explicit exclusions
• Added experimental feature validation to ensure excludeTools requires experimental mode and is not used in CUA mode
• Threaded the excludeTools parameter through the agent handler to both tools creation and system prompt generation
• Added comprehensive documentation with examples and available tools by mode

Issues found:

• The close tool is missing from both hybridTools and domTools arrays in the new buildToolsSection function, even though it exists in the actual toolset and is referenced in the guidelines section of the system prompt

Confidence Score: 4/5

• This PR is mostly safe to merge with one logical issue that needs fixing
• The implementation is clean and well-structured with proper validation and documentation. However, the missing close tool from the system prompt's tools list is a critical omission that could confuse the agent since the guidelines instruct it to use the close tool, but it won't be listed in the available tools section. This was working in the old implementation because the tool was never listed (existing issue), but the refactoring should have included it.
• Pay close attention to packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts - the close tool must be added to both tool arrays

Important Files Changed

Filename	Overview
.changeset/tiny-carrots-learn.md	Added changeset entry for the excludeTools feature - no issues
packages/core/lib/v3/types/public/agent.ts	Added comprehensive documentation for excludeTools option with examples and tool lists - well documented
packages/core/lib/v3/agent/utils/validateExperimentalFeatures.ts	Added validation logic to ensure excludeTools is experimental and not used in CUA mode - correctly implemented
packages/core/lib/v3/agent/tools/index.ts	Refactored tool filtering to support excludeTools parameter - clean implementation with proper filtering logic
packages/core/lib/v3/handlers/v3AgentHandler.ts	Threaded excludeTools parameter through handler to tools and system prompt - properly integrated
packages/core/lib/v3/agent/prompts/agentSystemPrompt.ts	Refactored tools section into buildToolsSection function with excludeTools support - well structured but missing close tool in tools list

Sequence Diagram

sequenceDiagram
    participant User
    participant AgentHandler as V3AgentHandler
    participant Validator as validateExperimentalFeatures
    participant PromptBuilder as buildAgentSystemPrompt
    participant ToolsFactory as createAgentTools
    participant FilterTools as filterTools
    participant LLM as Language Model

    User->>AgentHandler: execute({instruction, excludeTools: ["screenshot", "extract"]})
    AgentHandler->>Validator: validateExperimentalFeatures(excludeTools)
    alt CUA Mode
        Validator-->>AgentHandler: Error: excludeTools not supported in CUA
    else Experimental disabled
        Validator-->>AgentHandler: Error: requires experimental: true
    else Valid
        Validator-->>AgentHandler: ✓ Validation passed
    end
    
    AgentHandler->>PromptBuilder: buildAgentSystemPrompt({excludeTools})
    PromptBuilder->>PromptBuilder: buildToolsSection(mode, hasSearch, excludeTools)
    Note over PromptBuilder: Filter tools from<br/>system prompt description
    PromptBuilder-->>AgentHandler: System prompt (without excluded tools)
    
    AgentHandler->>ToolsFactory: createTools(excludeTools)
    ToolsFactory->>ToolsFactory: Create all tools
    ToolsFactory->>FilterTools: filterTools(allTools, mode, excludeTools)
    Note over FilterTools: 1. Filter by mode (dom/hybrid)<br/>2. Delete excluded tools
    FilterTools-->>ToolsFactory: Filtered toolset
    ToolsFactory-->>AgentHandler: Available tools
    
    AgentHandler->>LLM: generateText({tools, systemPrompt})
    Note over LLM: Agent only sees and can use<br/>non-excluded tools
    LLM-->>AgentHandler: Result
    AgentHandler-->>User: AgentResult

Loading

[greptile-apps]

_{5 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[miguelg719]

nice rearrangement, we could also centralize some of the commonly shared tools (goto, close..) to extend with the custom hybrid/dom ones

[miguelg719]

lgtm we should add a couple unit tests. Also should there be tools that cannot be disabled (i.e close)?