---
title: "Managing enabled tools and groups"
manual: "LLM Foundation"
version: "main"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:managing-enabled-tools-and-groups@main"
source: "Administration/ToolManagement.rst"
rendered: "2026-11-12T15:41:35+00:00"
---

# Managing enabled tools and groups {#managing-enabled-tools-and-groups}

## Managing tools {#administration-tools-manage}

The **AI > Operation > Tools** module lists every registered tool
with its global enable state and lets an admin toggle it. A **disabled** tool
is refused on every run, everywhere — the runtime gate is fail-closed, so a
disabled tool can never be offered to the model regardless of a skill's
`allowed-tools` or the per-run selection in the playground. Some built-in
tools (for example `get_env_raw` and `get_php_info_raw`) ship **disabled
by default** because they return unredacted, secret-bearing output; enable
them only deliberately.

An imported tool whose name is already registered is dropped; the existing
tool keeps its name. A failing tool provider retains the rows it supplied
before the failure, and healthy providers remain available. Optional logging
failures do not change either outcome.

A tool that is refused never reaches the model, so by itself the model cannot
tell it from a tool that does not exist. An extension that runs a chat can ask
`NetresearchNrLlmServiceToolUnavailableToolsResolverInterface` for
the tools one configuration and one backend user will NOT be offered, each
with the gate that holds it back — `toolDisabled`, `requiresAdmin`,
`configurationGroup`, `configurationExcluded` or `trustZone` — and pass
that to the model, which
can then say "there is a tool for that, it is not enabled for you"
([ADR-201](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-201@main)). A builtin tool the trust-zone gate only
observes is offered, and is not in that list; a remote (MCP) tool is always
enforced by that gate, so above the ceiling it is listed in either mode.
Remote tools are listed for administrators only.

![The Tools management module listing each built-in tool with an Enabled or Disabled badge and an Enable/Disable toggle](../Images/ToolsModule.png)

A tool that carries an **editor action** declaration
([ADR-152](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-152@main)) reads differently in that list: it shows an icon,
its translated name, one sentence written for a human, and the record types it
addresses — instead of the wire name and the description written for the
language model. Ten of the twenty-three writing tools declare one —
`create_record_draft` has no subject record and declares none
([ADR-197](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-197@main)), `attach_file_to_record` declares none for the
same reason ([ADR-212](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-212@main)), and the six of
[ADR-198](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-198@main) and `set_file_reference_alternative_text`
([ADR-230](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-230@main)) and the four site tools of [ADR-257](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-257@main)
are reached through the assistant only — and the wire name stays
visible as the technical detail the toggle acts on. A read-only tool is
unchanged.

The declaration is presentation only. It does not decide whether a tool writes
— that is the tool's declared effect — and it changes nothing about how a call
is fenced, approved or audited.

A declaration that throws leaves its row under the wire name and preserves
healthy declarations beside it. Failure to deliver its optional warning also
preserves module rendering and the tool's availability
([ADR-152](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-152@main)).

## Tool groups {#administration-tools-groups}

Every tool belongs to a **group** (its `getGroup()` value). The built-in
groups carry a translated name in the module header beside their identifier; a
group a third-party extension brings has no translated name and shows its
identifier alone. The built-in taxonomy:

| Group | Tools |
| --- | --- |
| `content` | `search_records`, `get_page_content`, `read_records`, `get_record_history`, `ask_choice`, `highlight_record` |
| `structure` | `get_pagetree`, `get_tca`, `read_fal_asset_meta`, `get_full_tca`, `get_table_schema`, `get_flexform_schema`, `resolve_url`, `validate_tca` |
| `system` | `get_env` (+ raw), `get_php_info` (+ raw), `fetch_logs`, `probe_url`, `list_extensions`, `list_scheduler_tasks`, `get_system_status`, `list_deprecations`, `list_middlewares` |
| `accounts` | `list_be_users` (+ raw), `list_be_groups` |
| `configuration` | `get_typoscript`, `get_tsconfig`, `fluid_resolve`, `check_typoscript`, `get_site_config`, `load_skill`, `list_redirects` |
| `code` | `get_last_exception`, `read_source`, `search_code` |
| `files` | `list_fal_storages`, `browse_fal_folder`, `search_fal_files`, `get_fal_references`, `find_missing_files` |
| `rag` | `site_rag_query`, `site_fetch_source` |
| `web` | `fetch_external_url` — the only group that reaches hosts outside the installation |
| `editing` | `update_page_metadata`, `set_page_social_image`, `set_file_alternative_text`, `update_fal_asset_meta`, `set_file_categories`, `attach_file_to_content_element`, `attach_file_to_record`, `move_content_element`, `create_content_element_draft`, `create_page_draft`, `create_translation_draft`, `create_record_draft`, `update_content_element`, `publish_record`, `delete_record`, `copy_record`, `move_page`, `replace_file_reference`, `set_file_reference_alternative_text`, `create_redirect`, `update_redirect`, `disable_redirect`, `clear_cache` — the only WRITING group |

`load_skill` loads an approved skill into an agent run's system message
(ADR-214). It is offered only to a run whose configuration has skills attached
as *loaded on demand* and at least one of them is an approved instruction; its
description lists those skills by uid, name and description. The skill
allow-list and the configuration's allowed tool groups do not restrict it, so
a skill declaring `allowed-tools: []` does not switch it off; the global tool
state and the trust zone do. Loading a skill grants no tools. It does not
require admin: a non-admin backend user's run may load a skill, because the
text it adds is an approved version an administrator vouched for, attached
to the configuration, and it widens nothing the user may do. In a run that
invokes a process skill the exemption does not hold; there the process
skill's approved declaration decides whether `load_skill` is offered.

Groups can be switched on three levels, and the result cascades
**fail-closed** — a tool is offered only when *every* level permits it:

1.  **Centrally** in the Tools module: each group header carries an
    Enable/Disable group toggle. A disabled group refuses all of its tools —
    including same-group tools installed later — and a per-tool override can
    **not** re-enable a tool inside a disabled group (predictable,
    fail-closed). Per-tool toggles keep working but take effect only once the
    group is enabled again.
1.  **Per configuration**: the **Allowed tool groups** field on an
    LLM configuration restricts agent runs with that configuration to tools of
    the selected groups (empty = all groups). This intersects with a skill's
    `allowed-tools` declaration.
1.  **Per run** in the playground: the tool checkboxes are grouped, and each
    group checkbox (de)selects its children.

Below the group level, a configuration can also exclude single tools — see
[Excluding single tools per configuration](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-tools-excluded@main).

Third-party extensions declare their own group per tool; the recommended
value is the extension key, so an admin can disable an extension's whole
tool family with one toggle. The design is recorded in
[ADR-043](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-043@main).

## Excluding single tools per configuration {#administration-tools-excluded}

The **Excluded tools** field on an LLM configuration (tab
**Access Control**, below **Allowed tool groups**) withholds single
tools from agent runs with that configuration. A configuration that may use
every tool of `editing` except `delete_record` keeps the group and excludes
that one tool. The field lists the registered tools by group; a name stored
earlier whose tool is no longer registered appears under **No longer
registered** and can be removed there.

An exclusion only narrows. It applies on top of the global state, the allowed
tool groups, a skill's `allowed-tools` and the trust zone, and can never
enable a tool any of them refuses. It also applies to `load_skill`, which the
skill allow-list and the group gate leave alone.

-   An excluded tool is not offered to the model. A call the model sends anyway
    is refused when it is executed.
-   Other configurations are not affected: they keep the tool.
-   A tool registered later is not excluded until it is selected here.
-   A run that waits in the queue, for an approval or for input is continued
    against the exclusions it started under together with the ones that apply
    when it resumes. An exclusion added meanwhile takes the tool away; one
    removed meanwhile does not give it back to that run.

The tools a configuration excludes are shown in two places: the Tools module
names, under each tool, the active configurations that exclude it, and the
**Governance** tab of **AI > Overview** lists the excluded
tools per active configuration. The list of tools not offered to a chat
([above](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-tools-manage@main)) reports such a tool with the
reason `configurationExcluded`. The design is recorded in
[ADR-261](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-261@main).