> For the complete documentation index, see [llms.txt](https://docs.3techagency.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.3techagency.com/documentation/reference-and-help/tools-and-permissions.md).

# Tools and permissions

Which tools the assistant can use, how approvals are decided, and how to allow a tool in one chat.

Every action the assistant takes is a **tool** (a WordPress ability). Whether a tool is offered, runs immediately, asks first or is refused depends on four layers, checked on every call.

```mermaid
flowchart LR
  A[Tool requested] --> B{Role allowed?<br/>Settings > Access}
  B -- no --> X[Refused]
  B -- yes --> C{Tool on?<br/>Integrations > Advanced tools}
  C -- no --> G[Allow card in chat]
  C -- yes --> D{Safety setting?<br/>files, DB, WP-CLI, code, users}
  D -- off --> X
  D -- ok --> E{Protected page?}
  E -- yes --> X
  E -- no --> F{Risk class}
  F -- Auto --> R[Runs, Undo available]
  F -- Ask --> P[Approval card]
```

## Risk classes

| Class     | Examples                                                                    | Behaviour                                   |
| --------- | --------------------------------------------------------------------------- | ------------------------------------------- |
| **Auto**  | Single-element edits, SEO field writes                                      | Runs straight away; Undo on the result card |
| **Ask**   | Deletes, bulk WooCommerce changes, code injection, user writes, broad edits | Pauses on an **Approval needed** card       |
| **Block** | Anything outside the conversation's tool list                               | Not offered to the model                    |

Once a turn has read third-party text (form entries, fetched page HTML), any write in that same turn is downgraded to ask-first, so instructions hidden in that text cannot quietly drive a change.

## Roles (Settings > Access)

Administrators always have every capability. Other roles start with none.

| Capability     | Lets a role                                                      |
| -------------- | ---------------------------------------------------------------- |
| Chat           | Open AI Chat and the in-editor panel                             |
| Approve writes | Approve pending changes on approval cards                        |
| Run tasks      | Open Tasks and run them                                          |
| Woo-only       | Restrict the role to WooCommerce tools (useful for Shop Manager) |

Role grants never override WordPress's own permissions: the user must still be able to edit the post, product or setting.

## Turn tools on or off (site-wide)

**Integrations > Advanced tools** has per-tool toggles grouped by plugin. A tool can be unavailable because its plugin is missing or inactive, its module is off, or its toggle is off. Changing these toggles is the only way to switch a tool on or off for the whole site.

## Allow a tool in one chat

If the assistant needs a tool that is not available in the current conversation, Chat shows a card instead of a dead end:

* **Allow X in this chat**: for a tool that is switched off for the site. One click (administrators only) allows it for this conversation only and the assistant continues automatically. Site-wide settings do not change and other chats do not get the tool.
* **Use X in this chat**: for a tool that is on for the site but outside this chat's list, for example in a Task conversation.
* Tools behind a safety setting (files, database, WP-CLI, custom code, user writes) are never one-click. The card explains this and links to **Settings > Advanced**.

The model cannot switch a tool on. Only a human click can. Before saying it cannot do something, the assistant searches the tool list (`wam/find-tools`), so a tool that exists but was not loaded is found rather than reported as missing. On sites with many plugins (over 40 tools), Chat sends the model a compact list and the search fills the gaps.

## Advanced safety settings

| Setting (Settings > Advanced) | Default                                              | Unlocks                                                                                        |
| ----------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| AI can use advanced tools     | Off                                                  | Filesystem, Database, WP-CLI, Custom Code and User-write tools, when also on in Advanced tools |
| Allow AI-written code         | Off                                                  | Loading activated PHP snippets. Each snippet is a draft until a human activates it in Sandbox. |
| Protected pages               | Cart, checkout, my-account and privacy policy always | Extra pages the AI may never write to. Refused outright, even with **Approve all**.            |

## WooCommerce tools

With WooCommerce 10.9 or newer, the assistant can list, query, get, create, update and delete products; list, query and get orders, update order status and add order notes; bulk-edit prices and stock with a dry-run preview; create and expire coupons; assign categories; and pull a store summary. Payment and shipping configuration, refunds and customer data export are not exposed as Chat actions.

See [Approvals, Undo and History](/documentation/work-safely/approvals-undo-and-history.md) for what happens after a tool runs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.3techagency.com/documentation/reference-and-help/tools-and-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.