The overlay
The overlay is an unversioned organizational layer, keyed by tool name and kept separate from any tool’s behavior. It applies to any tool in the namespace — a native plugin tool, a preset, or a tool of any other kind — never a preset-only concern. It has two parts:- Folders — real folder entities forming a tree. A folder has a name and an optional parent; nesting is endless through the parent chain.
- A per-tool row — for each tool that has one: its display name, the folder it is filed in, its user tags, and its visibility. Most tools never own a row — a tool with no row simply renders under its own name, unfiled, with only its native tags.
Display names
A per-tool row may set adisplay_name that overrides the label a UI renders.
When set, surfaces show the display name; when absent, they fall back to the tool
name. The real tool name stays identifiable — most surfaces render it beside the
display name, and where a compact surface shows the display name bare the raw name
is one picker or edit surface away — so a display name is a friendlier label, never
a rename. The name a caller invokes is unchanged.
The display name follows a tool everywhere the Studio lists one to choose: the
preset create form, agent composition, schedule creation, extension apply, the
Connectors pick step and the Manifest screen’s MCP editor each label a tool Display Name (raw_name), with the raw name
alone as the fallback. Agent composition’s selected-tool chips are the compact
exception — they carry the bare display name, with the raw name one picker or
edit surface away. A plugin’s own surfaces label the same way.
A display name is distinct from a tool’s description (its LLM-facing docstring)
— the description is the tool’s own behavioral text, while the display name is
purely a human label in the overlay.
Folders
Folders are entity-backed, not a string on each tool. You create a folder (at the root or under a parent), rename it, move it to a new parent, and delete it. The store enforces the tree’s integrity:- Sibling names are unique within a parent (root folders share the empty parent), so no two folders in the same place collide.
- A move that would form a cycle is refused — a folder can never become its own ancestor.
- A delete requires the folder empty of both subfolders and tool rows — you cannot orphan its contents by removing it.
One tree, a view per screen
There is one folder tree per deployment. Every screen that files tools — Tools, Presets and Agents in the Studio — shows the same tree, and a folder created, renamed, moved or deleted on one screen is the same folder on the others. Each screen draws its own view of that tree:- Tools draws every folder.
- Presets and Agents draw a folder when its subtree holds one of that screen’s own items (a preset, or an agent), when its subtree holds no tool at all, or when it is the parent of a folder they draw. A folder that holds only other tools is left out of the view, and an empty folder shows on every screen.
501 and every screen withdraws its
overlay actions at once.
Tags: two sources, one merged view
A tool can carry tags from two independent sources, and UIs show them merged:- Plugin-native tags are code-owned and read-only. A plugin declares them
on the tool itself (for example,
tags={"acme"}on a tool registration), so they ship with the tool and cannot be edited from a UI. - User tags are the overlay’s editable set. You add or replace them on a tool’s overlay row, and they persist independently of the plugin’s own tags.
acme by its plugin and
tagged reviewed by you appears under both.
Capability badges: informational, never enforced
Alongside tags, a tool can carry capability badges — short labels that flag what a tool touches or does, meant purely to inform the human scanning a tool list. Like tags, badges come from two independent sources and UIs show them merged:- Plugin-declared badges are code-owned. A plugin declares them on the tool
itself (Acme’s
acme_probedeclaresnetwork, for example), so they ship with the tool. - Operator-overlay badges are the overlay’s editable set, stored on a tool’s overlay row and managed from the CLI or API.
storage-read). To keep badges legible across a deployment, a small suggested
generic vocabulary is worth standardizing on — as guidance, not a rule:
Coin your own beyond these whenever a deployment needs a finer signal — the list
above is only a starting point, never a closed set.
Visibility: hidden is not security
The overlay’s visibility flag is tri-state:- Default (no user opinion) — the plugin-declared visibility applies. A plugin
may ship a tool hidden by default (Acme’s
acme_probedoes), and with no overlay opinion that declaration stands. - Shown — force the tool visible, overriding a plugin’s hidden default.
- Hidden — force the tool hidden.
Lifecycle
An overlay row is keyed by tool name, so the platform keeps it in step with the tools it describes:- A preset delete cascades its overlay rows away — deleting the preset removes the row keyed on its name and the row keyed on each extension branch tool bound off it.
- A preset rename re-keys each of those rows: the preset’s row to the new name, and a branch’s row to the new preset’s branch of the same extension. A row already under a destination name is replaced. The organization you gave a preset survives the rename that rebinds its tool.
- A plugin uninstall keeps the row. The tool it described is gone, so a UI hides the now-dangling entry; reinstalling the plugin brings the tool back under the same name and the row applies again.
Managing the overlay
Edit the overlay from the CLI withtai tool-meta — folders and per-tool rows:
set is a merge-patch — only the flags you pass are sent, so omitting a field
leaves it unchanged. In the Studio the Tools screen carries the
full per-tool edit dialog (display name, tags, badges, folder, and the three-way
visibility control); hidden tools are excluded from the screen outright, so unhiding
is a CLI/API operation (set visibility Shown). The Presets screen’s Edit
details dialog sets a preset’s display name, tags, and folder; the Agents screen’s
Move files an agent into a folder; the Babelfish Flows page edits the display
name, tags, and folder of each flow. Hide management stays on the Tools screen.
See also
tai tool-metareference — the full folder and overlay command set.- The screens — the Tools and Agents screens’ folders and the Tools edit dialog.
- Presets — a preset’s own record carries no organization; it rides this overlay like any tool.
- Babelfish — flows organize through the same overlay from the Flows page.

