Feature Request: Global default tools configuration for agents

Problem

When adding MCP servers or as new built-in tools are added, they're automatically
available to all agents. This causes:

Context window bloat from unused tool prompts
Need to manually disable tools in every agent configuration
No way to set a "baseline" of tools that agents inherit

Proposed Solution

Add a global defaultTools array that defines which tools are available to all
agents by default:

{
  "$schema": "https://opencode.ai/config.json",
  "defaultTools": ["read", "grep", "glob", "list"],
  "agent": {
    "myagent": {
      "description": "Custom agent",
      "tools": {
        "webfetch": true
      }
    }
  }
}

Behavior

• If defaultTools not set: Current behavior (all tools enabled by default) -
non-breaking
• If defaultTools is set: Only these tools are available by default, agents can
add more via their tools config
• Users can set "defaultTools": [] (empty array): Zero tools by default, opt-in
per agent

This allows clean agent contexts without repetitive configuration across all
agents.

@calvinalkan

@calvinalkan there is a tools object at both the agent level and the root of your config.

This means you can disable x or more tools for all agents by default and then enable per agent per tool.

Or you can enable for all agents and then disable per agent

I think that should allow you to accomplish what you are looking for here right?

@rekram1-node

@rekram1-node So e.g. this should work to disable all tools by default, including ones provided by MCP servers or new features added over time...?

  "tools": {
    "*": false,
  },

I think that should allow you to accomplish what you are looking for here right?

Oh, i'll check out the source to see how it works. I think it should be what I need.

I think this is missing in the config docs? Or am I blind?

This works for me:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "claude-sonnet-4-20250514",
  "tools": {
    "bash": false,
    "edit": false,
    "glob": false,
    "grep": false,
    "linear_*": false,
    "list": false,
    "lsp-diagnostics": false,
    "lsp-hover": false,
    "multiedit": false,
    "patch": false,
    "read": false,
    "task": false,
    "todoread": false,
    "todowrite": false,
    "webfetch": false,
    "write": false
  },
  "mcp": {
    "linear": {
      "type": "local",
      "command": ["pnpm", "exec", "mcp-remote", "https://mcp.linear.app/sse"],
      "enabled": true
    }
  }
}

Sadly, just doing

tools: {
  "*": false
}

does not work. Looks like the wildcard is not resolved in agent.ts

@calvinalkan

@calvinalkan I think we have these settings in a couple places in the docs, thx for pointing out issue with the generic wildcard false that should be working so I guess there is a bug there

aside from that wildcard not working does this address your issue properly?

Sadly, just doing

tools: {
"*": false
}
does not work. Looks like the wildcard is not resolved in agent.ts

That's odd, because it does seem to work for me.

E.g. if I have that, and then add another primary agent with no tools specified:

    "trevor": {
      "mode": "primary"
    },

... then it doesn't seem to be able to use webfetch or bash when I try.

This is opencode v0.13.7, hitting amazon-bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0.

In general I think the question of what tools are actually available/unavailable in a given context is a bit opaque. Perhaps if #2666 gets addressed that would help as one could then at least see what information the models are being fed.

Even from what is in the docs, it's hard to discern the rules. E.g. in docs/agents#tools, we have:

If no tools are specified, all tools are enabled by default.

OK, but what if some tools are specified? Are all other tools disabled in that case? That seems like the obvious inference, and I guess it would be sensible — but it's not explicit anywhere, and I haven't been able to establish the answer to this just by trying things out (maybe a skill issue on my part — again, #2666 would help here).

Okay, I tested this more deeply, and I can confirm it behaves as follows:

"*": false disables all tools globally, but the built-in plan and build agents still
have some tools enabled by default in the source code (they spread defaultTools but
start with an empty object, not hardcoded tools).

My config:

{
  "tools": { "*": false },
  "agent": {
    "plan": { "tools": { "linear_*": true } }
  }
}

This disables everything NOT explicitly enabled in any agent, then gives plan agent access to
Linear MCP.

So the wildcard works.

Another possible way to provide visibility of this would be to explicitly unpack the information in the API server, so that e.g. on the /agent endpoint, instead of (say):

{
  "name": "build",
  "tools": {
    "*": false,
    "write": true,
    "edit": true,
    "bash": true
  },
  ...

(which is what's there now, just combining the config from the top level with the per-agent config)

... we could have (e.g.):

{
  "name": "build",
  "tools": {
    "bash": true,
    "edit": true,
    "glob": false,
    "grep": false,
    "linear_*": false,
    "list": false,
    "lsp-diagnostics": false,
    "lsp-hover": false,
    "multiedit": false,
    "patch": false,
    "read": false,
    "task": false,
    "todoread": false,
    "todowrite": false,
    "webfetch": false,
    "write": true
    },
    ...

... if that makes sense?

right now we have a notion of permissions and one for tools, as part of the opentui migration these concepts will be merged and make these spreads and other behaviors both more intuitive and easier to work with (just fyi)

right now we have a notion of permissions and one for tools, as part of the opentui migration these concepts will be merged and make these spreads and other behaviors both more intuitive and easier to work with (just fyi)

IMO, current way is good and flexible, it just needs to be in the docs what the expected bevahiour is.

Navigation Menu

Repository navigation

Feature Request: Global default tools configuration for agents #2888

Problem

Proposed Solution

Behavior

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: Global default tools configuration for agents #2888

Description

Problem

Proposed Solution

Behavior

Activity

rekram1-node commented on Oct 1, 2025

rekram1-node commented on Oct 1, 2025

gimbo commented on Oct 1, 2025

calvinalkan commented on Oct 1, 2025

calvinalkan commented on Oct 1, 2025

rekram1-node commented on Oct 1, 2025

rekram1-node commented on Oct 1, 2025

gimbo commented on Oct 1, 2025

gimbo commented on Oct 1, 2025

calvinalkan commented on Oct 1, 2025

gimbo commented on Oct 1, 2025

rekram1-node commented on Oct 1, 2025

calvinalkan commented on Oct 1, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions