# Tool groups and what each one allows

By the end of this page you know what every tool group lets an agent do, what each one needs before it can be switched on, and which groups to leave off.

Every tool belongs to one group, and every group has its own switch on the **Settings** tab under **Tool groups**. The switches apply to every client, whichever way it connects. A group that is off does not exist for any client: its tools are not listed and cannot be called.

The screen shows the groups in three sets.

| Set | Groups |
|---|---|
| Block theme | Theme files, Site Editor templates, Global styles, Patterns, Search and replace in content |
| Site | Browse, Site administration, Abilities |
| Beyond the theme | Read files, HTTP requests |

Next to each group’s name the screen shows how many tools it has. When a group cannot work on this site, its checkbox is disabled and the reason is printed under it.

## How to read a tool

The **Tools** tab lists every tool, group by group, with a pill for the group (**On**, **Off** or **Unavailable**) and two badges per tool.

- **Read-only**, **Write** or **Destructive**. A destructive tool asks for confirmation before it runs: in the browser while **Confirm destructive tools** is on, and in the client itself for a remote client.
- **Browser + HTTP** or **Browser only**. A browser-only tool needs a tab and is never offered to a remote client.

Each row also has an **Agent description**: the text the agent reads to decide how to use the tool.

## Block theme

These are the groups the plugin is built around. All of them start off.

### Theme files

11 tools. Needs the `edit_theme_options` and `edit_themes` capabilities, the same ones the theme file editor in wp-admin needs. WordPress removes `edit_themes` when `DISALLOW_FILE_EDIT` or `DISALLOW_FILE_MODS` is set, and on a multisite network only a Super Admin holds it.

The tools work inside the active theme’s folder, on `.html`, `.css`, `.js` and `.scss` files and the root `theme.json`. They never write PHP.

- Read: `btm.theme-list-files`, `btm.theme-read-file`, `btm.theme-search`
- Write: `btm.theme-create-file`, `btm.theme-update-file`, `btm.theme-apply-changes`, `btm.theme-delete-file`
- Undo: `btm.theme-list-change-sets`, `btm.theme-revert-change-set`, `btm.theme-list-backups`, `btm.theme-restore-file`

See [Edit theme files: change sets, backups and undo](https://w4dev.com/docs/block-theme-mcp/theme-files-change-sets-backups-undo/).

### Site Editor templates

9 tools. Needs `edit_theme_options` and an active block theme. The tools edit templates and template parts the way the Site Editor saves them, in the database.

`btm.template-list`, `btm.template-read`, `btm.template-revisions`, `btm.template-create`, `btm.template-update`, `btm.template-restore-revision`, `btm.template-reset`, `btm.template-delete`, `btm.template-save-to-theme`. The last one writes a file, so it also needs **Theme files** switched on.

See [Site Editor templates](https://w4dev.com/docs/block-theme-mcp/site-editor-templates/).

### Global styles

5 tools. Needs `edit_theme_options` and an active block theme. The tools read and change the styles and settings you would otherwise edit in the Site Editor’s Styles panel: `btm.styles-read`, `btm.styles-update`, `btm.styles-revisions`, `btm.styles-restore-revision`, `btm.styles-reset`.

See [Global styles](https://w4dev.com/docs/block-theme-mcp/global-styles/).

### Patterns

7 tools. Needs `edit_theme_options` and an active block theme. The tools list and read every pattern, and create and change your own patterns: `btm.pattern-list`, `btm.pattern-read`, `btm.pattern-create`, `btm.pattern-update`, `btm.pattern-revisions`, `btm.pattern-restore-revision`, `btm.pattern-delete`.

See [Patterns](https://w4dev.com/docs/block-theme-mcp/patterns/).

### Search and replace in content

2 tools. Needs `edit_others_posts` and `edit_theme_options`. `btm.content-search` finds text or a CSS class in saved posts, pages, templates and patterns. `btm.content-replace` changes it, in two steps, with a revision saved before every write.

See [Search and replace in content](https://w4dev.com/docs/block-theme-mcp/search-and-replace-in-content/).

## Site

Small groups for finding the way around a site. All three start on.

### Browse

5 tools, no extra requirement.

- `btm.site-info`: site addresses, WordPress and PHP versions, and which groups are on.
- `btm.site-list`: the sites the current user can reach. One row on a single site.
- `btm.browse-navigate`, `btm.browse-current-url`, `btm.browse-open-tab`: move the browser tab. Browser only.

### Site administration

1 tool, `btm.site-rename`, which changes the site’s display name. Needs `manage_options`.

### Abilities

One tool per Ability that plugins on your site have registered with the WordPress Abilities API and exposed. The tool takes the Ability’s name with the slash turned into a dot: `my-plugin/get-thing` becomes `my-plugin.get-thing`.

An Ability becomes a tool when it is registered with `show_in_rest`, or when its own `mcp` meta sets `public` to `true`. **Expose non-REST abilities**, the switch directly under **Abilities**, turns every other registered Ability into a tool too. It starts off.

An Ability tool asks for confirmation unless the Ability declares itself read-only or not destructive.

## Beyond the theme

The screen introduces this set with: “These reach past the theme: other files on the server, and any request your account can make. Leave them off unless you need them.” Both start off.

### Read files

3 tools: `btm.files-read`, `btm.files-list`, `btm.files-exists`. Needs `manage_options`, and a Super Admin account on a multisite network. Paths are confined to `wp-content`.

### HTTP requests

1 tool, `btm.request`, browser only. It sends requests to your own site with your browser session’s cookies. With this group on, the agent can make any request your account can make on the site, wp-admin screens included. That is the same as handing it your logged-in session, so switch it on only when you want an agent driving the whole site.

Requests that write are refused for wp-admin, `wp-login.php`, `xmlrpc.php`, the plugin’s own routes and Ability runs, and every other write asks for confirmation first.

## A sensible starting point

For theme work, switch on **Theme files** and **Site Editor templates**, and add **Search and replace in content** when a change has to reach saved content too. Leave everything under **Beyond the theme** off.

Source: https://w4dev.com/docs/block-theme-mcp/tool-groups/